Para o negócio: cada família tem destinos próprios. O
charge.updated com o chargeback formalizado, por exemplo, chega só no postbackUrl da cobrança, e o aviso de aprovação de subconta chega só na URL de aviso de status da subconta. Defina com o time técnico quais destinos a operação precisa antes de ir para produção.Destinos de entrega
Os eventos são roteados pela conta dona do recurso. A regra completa está em Quem recebe cada evento.
Todos os eventos
subscription.trial_started e subscription.trial_ended existem no contrato de tipos, mas não são entregues hoje. Para acompanhar o trial, use subscription.activated e subscription.renewed, que trazem o objeto trial. Não há evento para a liberação de um bloqueio nem para a criação de um saque.Formato por família
A explicação completa, com exemplos, está em Formato por família.
Envelope padrão (cobrança e assinatura)
Postback legado (charge.updated)
Sem id e sem livemode. O data é a cobrança em camelCase, com isBlocked, blockedAt e blockedReason no bloqueio e, no pré-chargeback, chargebackAlertRefunded e chargebackAlertReason.
Envelope de saque
Semlivemode. O id da raiz é o id da solicitação de saque. Campos em camelCase, valores em texto decimal.
Aviso de status de conta
Sem envelope: o corpo é o próprio objeto da notificação, em camelCase.rejectionReason aparece só em rejected e correcting. date é a data de referência do status.
Confirmação, entrega e deduplicação
- Confirmação de recebimento: só uma resposta
2xxem até 10 segundos conta como entregue. Redirecionamentos não são seguidos. - Entrega e novas tentativas: veja Entrega e retentativas.
- Deduplicação: o mesmo evento pode chegar mais de uma vez. A chave de cada formato está na receita de deduplicação.
- Teste e produção: a mesma lista de endpoints recebe os dois. Separe os eventos de cobrança por
livemodeeis_test(isTestnocharge.updated). Saques e avisos de conta não têm marcação de teste.
Segurança
- Os webhooks não trazem assinatura HMAC: confirme o estado na API antes de uma ação crítica (veja Regras de negócio dos webhooks).
- Use sempre HTTPS no endpoint.
- Aplique limite de requisições no seu endpoint.
- Responda rápido e processe depois: devolva
2xxantes de executar lógica pesada.
Como simular eventos
No sandbox,POST /v1/charges/{id}/resend-webhook gera um evento novo, com id novo, para uma cobrança de teste, com o status que você escolher (paid, pending, refused, failed, refunded, in_analysis ou authentication_required). O evento vai para o postbackUrl da cobrança e para os endpoints da própria conta. O payload simulado não é idêntico ao real, então não o use como referência de schema.
Guias de cada família
Webhooks de cobrança
Payload completo de cada evento
charge.* e do charge.updated.Webhooks de assinatura
Eventos
subscription.*, objeto charge e tipos de cancelamento.Webhooks de saque
payout.approved e payout.rejected das subcontas.Webhooks de conta
Avisos de aprovação, correção e bloqueio de subcontas.
Veja também
Visão geral de webhooks
Destinos, formatos, entrega e deduplicação.
Status de cobrança
O que cada status significa e o que fazer.

