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.

Atualizado em 09/11/2026 Recurso do plano: Webhooks

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

A página Eventos e payloads com o catálogo aberto

Formato#

Cada evento chega como um POST com corpo JSON (UTF-8). O envelope é sempre o mesmo:

CampoO que traz
idId único do evento. Igual em todo reenvio: use para não processar duas vezes.
typeO evento, ex.: commission.approved.
api_versionA versão do formato.
created_atQuando o evento aconteceu (ISO 8601, UTC).
testtrue nos eventos enviados pelo botão Enviar teste (dados fictícios).
brandid, slug e name da marca.
data.objectO registro completo como estava no envio. O tipo vem em data.object.object.
data.previous_attributesOs 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_at ou confira o status atual no objeto.

Cabeçalhos#

CabeçalhoO que traz
webhook-idId do evento (o mesmo do corpo).
webhook-timestampSegundos Unix do envio. Recuse se estiver a mais de 5 minutos do seu relógio.
webhook-signaturev1,<base64>: HMAC-SHA256 de {webhook-id}.{webhook-timestamp}.{corpo} com o segredo do endpoint.
x-hub-eventO tipo do evento, para rotear sem ler o corpo.
x-hub-delivery-idId desta entrega (muda a cada reenvio manual).
x-hub-attemptNú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#.

  1. Pegue o segredo na página do webhook (começa com whsec_).
  2. Tire o prefixo whsec_ e decodifique o resto em base64: essa é a chave.
  3. Monte o texto webhook-id + . + webhook-timestamp + . + corpo exatamente como chegou (antes de fazer parse do JSON).
  4. Calcule o HMAC-SHA256 desse texto com a chave e codifique em base64.
  5. Compare com a parte depois de v1, no webhook-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#

GrupoEventos
Participantesaffiliate.created, affiliate.activated, affiliate.paused, affiliate.blocked, affiliate.updated
Candidaturasapplication.received, application.approved, application.rejected
Vendasorder.attributed, order.paid, order.shipped, order.delivered, order.cancelled, order.refunded, order.chargeback
Comissõescommission.created, commission.approved, commission.paid, commission.reversed, commission.rejected
Pagamentospayout.created, payout.approved, payout.paid, payout.failed
Cuponscoupon.created, coupon.activated, coupon.paused, coupon.expired
Recebidosshipment.created, shipment.shipped, shipment.delivered, shipment.returned, shipment.canceled
Conteúdomention.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.

Este artigo ajudou?

Não resolveu?

Fale com a gente. A mensagem já vai com a tela e o artigo, para agilizar o atendimento.

Leia também