Eventos, payload e assinatura dos webhooks
Os 39 eventos dos webhooks, o formato do JSON, os cabeçalhos, como validar a assinatura (Standard Webhooks) e a política de reenvio.
Este artigo é para quem vai receber os webhooks no seu sistema (geralmente o time técnico ou quem monta a automação). A referência completa, com um exemplo de JSON para cada evento, fica em Configurações › Webhooks › Eventos e payloads.
No painel: /app/configuracoes/webhooks/eventos
Formato#
Cada evento chega como um POST com corpo JSON (UTF-8). O envelope é sempre o mesmo:
| Campo | O que traz |
|---|---|
id | Id único do evento. Igual em todo reenvio: use para não processar duas vezes. |
type | O evento, ex.: commission.approved. |
api_version | A versão do formato. |
created_at | Quando o evento aconteceu (ISO 8601, UTC). |
test | true nos eventos enviados pelo botão Enviar teste (dados fictícios). |
brand | id, slug e name da marca. |
data.object | O registro completo como estava no envio. O tipo vem em data.object.object. |
data.previous_attributes | Os valores anteriores do que mudou (ex.: {"status": "pending"}), ou null. |
- Valores em reais vêm como número decimal, com a moeda em
currency. - Campos sem valor vêm como
null, nunca somem. Campos novos podem ser acrescentados sem aviso: não deixe a integração quebrar com eles. - CPF, chave Pix e dados bancários nunca são enviados.
- A ordem de chegada não é garantida. Compare
created_atou confira o status atual no objeto.
Cabeçalhos#
| Cabeçalho | O que traz |
|---|---|
webhook-id | Id do evento (o mesmo do corpo). |
webhook-timestamp | Segundos Unix do envio. Recuse se estiver a mais de 5 minutos do seu relógio. |
webhook-signature | v1,<base64>: HMAC-SHA256 de {webhook-id}.{webhook-timestamp}.{corpo} com o segredo do endpoint. |
x-hub-event | O tipo do evento, para rotear sem ler o corpo. |
x-hub-delivery-id | Id desta entrega (muda a cada reenvio manual). |
x-hub-attempt | Número da tentativa (1, 2, 3…). |
Validar a assinatura#
A assinatura segue o padrão Standard Webhooks, que tem bibliotecas prontas (standardwebhooks) para Node, Python, PHP, Go, Ruby, Java e C#.
- Pegue o segredo na página do webhook (começa com
whsec_). - Tire o prefixo
whsec_e decodifique o resto em base64: essa é a chave. - Monte o texto
webhook-id+.+webhook-timestamp+.+ corpo exatamente como chegou (antes de fazer parse do JSON). - Calcule o HMAC-SHA256 desse texto com a chave e codifique em base64.
- Compare com a parte depois de
v1,nowebhook-signature(pode haver várias, separadas por espaço), usando comparação em tempo constante.
A página Eventos e payloads tem exemplos prontos em Node (com e sem biblioteca) e PHP.
Resposta e reenvio#
- Responda com qualquer status 2xx em até 10 segundos. O corpo da resposta é ignorado (os primeiros 2 KB ficam no histórico).
- Redirecionamentos (3xx) não são seguidos: cadastre a URL final.
- Sem 2xx, a plataforma tenta de novo depois de 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h: até 8 tentativas, ao longo de quase 2 dias. Depois disso, a entrega fica como Falhou e pode ser reenviada pelo painel.
- Um endpoint que falha por mais de 3 dias seguidos, sem nenhuma entrega aceita, é desligado automaticamente e a equipe é avisada.
- Enquanto o webhook está pausado, nenhum evento é gerado para ele.
Os eventos#
| Grupo | Eventos |
|---|---|
| Participantes | affiliate.created, affiliate.activated, affiliate.paused, affiliate.blocked, affiliate.updated |
| Candidaturas | application.received, application.approved, application.rejected |
| Vendas | order.attributed, order.paid, order.shipped, order.delivered, order.cancelled, order.refunded, order.chargeback |
| Comissões | commission.created, commission.approved, commission.paid, commission.reversed, commission.rejected |
| Pagamentos | payout.created, payout.approved, payout.paid, payout.failed |
| Cupons | coupon.created, coupon.activated, coupon.paused, coupon.expired |
| Recebidos | shipment.created, shipment.shipped, shipment.delivered, shipment.returned, shipment.canceled |
| Conteúdo | mention.created, content_license.requested, content_license.accepted, content_license.declined, content_license.revoked, content_license.expired |
Além desses, o webhook.ping só é enviado pelo botão Enviar teste, para conferir a conexão e a assinatura.
Perguntas frequentes#
O order.attributed chega mais de uma vez para o mesmo pedido?
Vem uma vez por pedido e pessoa. As mudanças depois disso (pago, enviado, cancelado...) chegam como eventos próprios.
Troquei o segredo e as assinaturas pararam de bater
O segredo novo vale a partir da próxima entrega. Atualize a variável de ambiente no seu servidor com o segredo novo.

