Skip to main content
Todo webhook da Chargefy é entregue de forma assíncrona, assinado com HMAC-SHA-256 e reentregue automaticamente em caso de falha. A assinatura segue o padrão Standard Webhooks por completo — inclusive o formato do secret — então você verifica com qualquer biblioteca compatível, sem reimplementar HMAC manual.
O que você precisa garantir no seu endpoint
  1. Aceitar POST em uma URL HTTPS.
  2. Verificar a assinatura antes de processar o corpo.
  3. Responder com um status 2xx em até 20 segundos.
O resto — fila, retry, rotação de secret, fan-out — é responsabilidade da Chargefy.

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 o POST. 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 de 2xx 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 200 primeiro, processe depois. Persista ou enfileire o evento e devolva o 2xx imediatamente. 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 com 2xx e descarte em silêncio. Reserve 4xx/5xx para falha real de processamento — qualquer não-2xx entra na agenda de reentrega e vira ruído dos dois lados.
  • Deduplique pelo id do 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 objeto event. 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:

Assinatura

Cada requisição carrega os headers abaixo. A assinatura cobre o id, 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:
Os bytes decodificados do base64 (após o prefixo 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.
Sempre receba o corpo bruto (express.raw(), req.text(), request.get_data()). Se o corpo for parseado como JSON antes da verificação, a serialização pode diferir do que foi assinado e a assinatura não vai bater.

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 campo id 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

Este recurso só está disponível para Chargefy for Platforms. Use events_from: "platform" quando o endpoint precisa receber eventos de suas organizações filhas.
Cada endpoint ouve exatamente um fluxo de eventos, escolhido na criação (campo events_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:
  1. Os endpoints events_from: organization da própria organização que originou o evento (se ela tiver algum inscrito).
  2. Os endpoints events_from: platform de cada plataforma ativa que opera essa organização filha.
Os eventos 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.
O reenvio é a forma de reproduzir exatamente um evento armazenado. Para validar o shape mais recente de um recurso, gere um novo evento em sandbox.

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

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.
Nunca processe um webhook sem validar a assinatura HMAC. Sem isso, qualquer um que conheça sua URL pode forjar eventos.
Grave o id (evt_...) e ignore repetições. Reentregas e reenvios manuais tornam a entrega at-least-once.
URLs de webhook devem usar HTTPS. Endpoints HTTP não são aceitos.
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.