Webhooks

Receba notificações em tempo real quando produtos, estoque ou pedidos mudam na loja.

Como inscrever

Com o escopo webhooks:manage, crie uma inscrição apontando para a sua URL e os eventos desejados. A resposta traz uma secret (exibida uma vez) usada para validar a assinatura.

POST /api/v1/webhooks

curl -X POST https://app.sellitbr.com/api/v1/webhooks \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seuapp.com/webhooks/sellit",
    "events": ["product.updated", "stock.updated", "order.shipped"]
  }'

Eventos disponíveis

Escopo	Permite
product.created	Produto criado
product.updated	Produto atualizado
product.deleted	Produto excluído
stock.updated	Saldo de estoque alterado
order.created	Pedido criado
order.paid	Pedido pago
order.shipped	Pedido enviado / status de envio atualizado
order.refunded	Pedido reembolsado

Formato da entrega

A Sellit envia um POST para sua URL com o corpo abaixo e os cabeçalhos X-Sellit-Event e X-Sellit-Signature-256.

POST https://seuapp.com/webhooks/sellit

// Estrutura comum a todos os eventos:
{
  "event": "<nome-do-evento>",
  "workspaceId": "ws_123",
  "data": { /* payload específico do evento */ }
}

Payloads por evento:

product.created / product.deleted

{ "id": "prod_abc", "name": "Camiseta Premium" }
{ "id": "prod_abc" }

product.updated

// Atualização de campos:
{ "id": "prod_abc", "fields": ["price", "description"] }
// Atualização de variações:
{ "id": "prod_abc", "variants": 3 }

stock.updated

// Produto simples:
{ "id": "prod_abc", "quantity": 42 }
// Variação:
{ "id": "prod_abc", "sku": "CAM-P-AZ", "quantity": 20 }

order.created / order.paid / order.refunded

{ "orderId": "ord_xyz" }

order.shipped

{
  "orderId": "ord_xyz",
  "statusShipping": "sent",
  "codeShipping": "BR123456789BR"
}

Use o campo workspaceId para identificar qual loja gerou o evento quando você gerencia múltiplos clientes com um único endpoint.

Política de reenvio

Se sua URL retornar um código fora do intervalo 2xx (ou ocorrer timeout de rede), a Sellit reenvio o evento automaticamente com backoff exponencial, até 5 tentativas no total. Entregas com falha ficam registradas no log da inscrição.

Responda sempre com 2xx assim que receber o evento, mesmo que o processamento seja assíncrono.
Implemente idempotência usando o par event + workspaceId + data.id para deduplicar reenvios.
Não bloqueie a resposta esperando que o processamento termine — responda rápido e processe em background.

Validando a assinatura

A assinatura é o HMAC-SHA256 do corpo cru usando a secret da inscrição, no formato sha256=<hash>. Compare com o header recebido.

Node.js

import { createHmac } from "node:crypto"

function isValid(rawBody, signatureHeader, secret) {
  const hash = createHmac("sha256", secret).update(rawBody, "utf8").digest("hex")
  return signatureHeader === `sha256=${hash}`
}

Calcule o HMAC sobre o corpo exatamente como recebido (bytes crus), antes de qualquer parsing JSON. Entregas com falha são reprocessadas automaticamente com novas tentativas.