O que você precisa garantir no seu endpoint
- Aceitar
POSTem uma URL HTTPS. - Verificar a assinatura antes de processar o corpo.
- Responder com um status 2xx em até 20 segundos.
Respostas rápidas
Como a entrega funciona
A entrega é desacoplada do evento. Quando algo acontece (um pagamento confirma, uma assinatura é criada), a Chargefy grava o evento e enfileira a entrega; um worker dedicado drena a fila e faz oPOST. Isso garante que um endpoint lento ou fora do ar nunca trava a operação que originou o evento.
Endpoints inscritos no mesmo fluxo recebem o mesmo
event.id, mas cada endpoint tem seu próprio ciclo de entrega e retry. Assim, a falha de um endpoint não atrasa nem altera a entrega dos demais.Parâmetros de entrega
Reentrega automática
Qualquer falha — status fora de2xx ou timeout — reagenda a entrega sozinha. O intervalo até a próxima tentativa cresce a cada falha:
Os horários têm precisão de ~1 minuto (o ciclo do worker). A lógica da agenda: as primeiras reentregas vêm rápido, para falha transitória (deploy, reinício, instabilidade de segundos); as últimas dão espaço para indisponibilidade longa. Na prática, um endpoint que ficar fora do ar por horas — ou até ~3 dias — recupera as entregas pendentes sozinho quando voltar, sem nenhuma ação sua.
Esgotadas as 9 tentativas, a entrega vira falha permanente: ela não some — fica registrada no dashboard — mas só chega de novo por reentrega manual, possível enquanto o payload existir.
Boas práticas no seu endpoint
- Responda
200primeiro, processe depois. Persista ou enfileire o evento e devolva o2xximediatamente. Processamento pesado dentro dos 20 segundos arrisca timeout — que conta como falha e gera reentrega de um evento que você já recebeu. - Evento que você decide ignorar também merece
200. Tipo que não interessa, organização que você não reconhece, duplicata: reconheça com2xxe descarte em silêncio. Reserve4xx/5xxpara falha real de processamento — qualquer não-2xx entra na agenda de reentrega e vira ruído dos dois lados. - Deduplique pelo
iddo evento — reentrega significa que o mesmo evento pode chegar mais de uma vez. O padrão completo está em Idempotência. - Acompanhe as entregas no dashboard (Configurações → Webhooks): cada tentativa registra status, código HTTP e corpo da resposta do seu servidor — é o primeiro lugar pra olhar quando algo não chegou.
Retenção do payload
O payload e o registro do evento são preservados sem prazo de expiração automático. A Chargefy não esvazia o corpo de eventos antigos: ele continua disponível para auditoria, debug e reentrega junto dos metadados de cada tentativa (status, data, HTTP code e corpo de resposta truncado).A reentrega usa o payload original armazenado no evento. Ela não reconstrói
nem atualiza o conteúdo com o estado atual do recurso.
O payload do evento
O corpo entregue usa o objetoevent. O recurso afetado vive em data.object e segue o mesmo contrato público retornado pela API. Quando existir, data.previous_attributes contém somente os valores anteriores dos campos alterados.
Esta página trata do transporte desse objeto. Consulte:
- objeto event para o envelope e seus campos;
- catálogo de eventos para os valores de
type; - a página individual de cada evento para o formato de
data.object.
Assinatura
Cada requisição carrega os headers abaixo. A assinatura cobre oid, o timestamp e o corpo bruto — qualquer re-serialização do corpo invalida a assinatura.
Formato do secret
Cada endpoint tem um secret no formato canônico:whsec_) são a chave do HMAC. Esse é exatamente o ponto que garante compatibilidade com as bibliotecas Standard Webhooks: você passa o secret inteiro, com prefixo, e a lib cuida da decodificação.
Algoritmo de assinatura
A string assinada é a concatenação de três partes separadas por ponto:Verificação
A forma mais simples e segura é usar uma biblioteca compatível com Standard Webhooks: ela decodifica o secret, valida a janela de timestamp, faz comparação constant-time e suporta múltiplas assinaturas durante rotação. Existe implementação oficial em Node, Python, Ruby, Go, PHP, Java, C# e Rust.Verificação manual
Se preferir não usar uma biblioteca, o algoritmo é direto:1
Valide a janela de tempo
Rejeite se
webhook-timestamp estiver fora de ±5 minutos do horário atual. Isso bloqueia replay de requisições antigas capturadas.2
Monte a string assinada
signed = ${webhook - id}.${webhook - timestamp}.${raw_body}, usando o corpo bruto exatamente como recebido.3
Decodifique o secret
Remova o prefixo
whsec_ e decodifique o restante de base64. Esses bytes são a chave do HMAC.4
Calcule e compare
esperado = base64(HMAC_SHA256(chave, signed)). Compare (constant-time) contra cada assinatura no header webhook-signature, ignorando o prefixo v1,. Aceite se qualquer uma bater.Verificação manual (TypeScript / Web Crypto)
Rotação de secret
Cada entrega da Chargefy usa o secret ativo do endpoint. Ao usar Resetar secret, o novo secret passa a valer imediatamente. Para trocar sem uma janela de rejeição:1
Crie um endpoint temporário
Cadastre a mesma URL, os mesmos eventos e o mesmo
events_from. Guarde o novo secret retornado na criação.2
Aceite os dois secrets
Atualize seu servidor para tentar a verificação com o secret antigo e, se ela falhar, com o novo. Deduplique pelo
event.id, pois os dois endpoints podem entregar o mesmo evento durante a transição.3
Confirme e remova o antigo
Depois que o endpoint novo estiver respondendo
2xx, remova o endpoint antigo e mantenha apenas o novo secret.Idempotência
Reentregas e reenvios manuais significam que o mesmo evento pode chegar mais de uma vez. Trate a entrega como at-least-once: garanta que processar o mesmo evento duas vezes não duplica efeitos no seu sistema. O campoid do payload (igual ao header webhook-id) é estável por evento. Use-o como chave de deduplicação:
1
Persista o id do evento
Ao receber, tente gravar
evt_... em uma tabela com restrição de unicidade.2
Pule duplicatas
Se o
id já existe, responda 200 e não reprocesse — a Chargefy já considera a entrega concluída.3
Confirme o estado atual, não a ordem
A ordem de entrega entre eventos diferentes não é garantida.
data.object é o snapshot completo do momento do evento, mas pode estar desatualizado quando chegar. Antes de aplicar uma transição terminal, consulte o recurso pelo ID e não deixe falha/cancelamento rebaixar um pagamento já succeeded ou uma session já paid.Fan-out para plataformas
Cada endpoint ouve exatamente um fluxo de eventos, escolhido na criação (campoevents_from, imutável depois):
Não existe endpoint com os dois fluxos misturados: quem precisa dos dois usa dois endpoints — pode ser a mesma URL, cada um com seu secret.
Quando uma organização filha origina um evento financeiro ou operacional, a entrega vai para:
- Os endpoints
events_from: organizationda própria organização que originou o evento (se ela tiver algum inscrito). - Os endpoints
events_from: platformde cada plataforma ativa que opera essa organização filha.
organization.* são a exceção: pertencem ao contrato de Chargefy for Platforms e são entregues somente aos endpoints events_from: platform. Endpoints events_from: organization não podem assiná-los.
O evento é o mesmo nos dois casos: mesmo event.id, mesmo payload e mesma organização de origem. Só muda o endpoint destinatário. Em ambos, o campo top-level organization aponta para a organização que originou o evento (a organização filha), nunca para a organização dona da plataforma.
Isso permite identificar de qual organização filha o evento veio lendo
organization, sem precisar de nenhum campo extra de relacionamento. Cada endpoint tem tentativas e retries independentes, mas todos os destinos da mesma ocorrência compartilham o mesmo event.id.Reentrega manual
Se um endpoint ficou fora do ar e o evento esgotou as tentativas automáticas — ou se você só quer reprocessar um evento — é possível reenviar manualmente pelo dashboard, em Configurações → Webhooks → Entregas.Desenvolvimento local
Para testar webhooks na sua máquina, exponha a porta local com um tunnel HTTPS e cadastre a URL gerada como endpoint:Boas práticas
Responda rápido (menos de 20s)
Responda rápido (menos de 20s)
Verifique a assinatura, persista o evento e responda
200 imediatamente. Processe a lógica pesada em background. Acima de 20 segundos a entrega é considerada falha e reentregue.Verifique a assinatura sempre
Verifique a assinatura sempre
Nunca processe um webhook sem validar a assinatura HMAC. Sem isso, qualquer um que conheça sua URL pode forjar eventos.
Dedupe pelo id do evento
Dedupe pelo id do evento
Grave o
id (evt_...) e ignore repetições. Reentregas e reenvios manuais tornam a entrega at-least-once.Use HTTPS
Use HTTPS
URLs de webhook devem usar HTTPS. Endpoints HTTP não são aceitos.
Monitore as entregas
Monitore as entregas
Acompanhe o status em Configurações → Webhooks → Entregas e investigue falhas persistentes antes que esgotem as tentativas.
Solução de problemas
Próximos passos
Catálogo de eventos
Consulte todos os tipos aceitos e seus payloads.
Escolher eventos
Assine somente os eventos que produzem ações no seu sistema.
Objeto event
Entenda o envelope,
data.object e previous_attributes.Criar endpoint
Configure URL, eventos, origem e secret de assinatura.

