Mecanismo de Entrega
Webhooks são processados de forma assíncrona via fila Redis (BullMQ):- Um evento ocorre na plataforma (ex: pagamento confirmado)
- O evento é adicionado à fila de webhooks
- Um worker processa a fila e envia o
POSTpara cada endpoint inscrito - Se a entrega falhar, o retry automático é acionado
Configurações de Entrega
| Parâmetro | Valor |
|---|---|
| Timeout por tentativa | 20 segundos |
| Máximo de retries | 10 tentativas |
| Backoff | Exponencial |
| Retenção de payload | 30 dias |
Após 30 dias, o payload do evento é removido automaticamente (archival), mas os metadados da entrega (status, data, HTTP code) são mantidos.
Retry Automático
Quando seu endpoint retorna um status diferente de2xx ou não responde dentro de 20 segundos, a Chargefy automaticamente reagenda a entrega com backoff exponencial.
| Tentativa | Delay aproximado |
|---|---|
| 1ª | Imediato |
| 2ª | ~1 minuto |
| 3ª | ~5 minutos |
| 4ª | ~30 minutos |
| 5ª | ~2 horas |
| 6ª | ~8 horas |
| 7ª-10ª | Intervalos crescentes |
Verificação de Assinatura HMAC
Todos os webhooks são assinados usando HMAC-SHA256 seguindo o padrão Standard Webhooks.Headers de Assinatura
Cada requisição de webhook inclui os seguintes headers:| Header | Descrição | Exemplo |
|---|---|---|
webhook-id | ID único do evento | evt_abc123 |
webhook-timestamp | Timestamp Unix (segundos) | 1710244200 |
webhook-signature | Assinatura HMAC-SHA256 | v1,K7gNU3sdo+OL0wNh... |
content-type | Tipo do conteúdo | application/json |
user-agent | Agente da requisição | chargefy.com webhooks |
Corpo JSON (payload)
O corpo é JSON com campos de primeiro nível nesta ordem:| Campo | Descrição |
|---|---|
type | Tipo do evento (ex.: subscription.active) |
id | UUID do evento — o mesmo valor do header webhook-id e do registro em entregas |
timestamp | ISO 8601 do momento em que o evento foi criado |
data | Objeto com os dados específicos do evento |
Eventos antigos (antes desta convenção) podem não incluir
id no corpo; use sempre o header webhook-id para verificação de assinatura e idempotência.Como verificar
A assinatura é calculada sobre a string:{webhook_id}.{timestamp}.{payload_json}
Múltiplas Assinaturas
O headerwebhook-signature pode conter múltiplas assinaturas separadas por espaço. Isso permite rotação de secrets sem downtime:
Boas Práticas
Responda rápido (< 20s)
Responda rápido (< 20s)
Processe webhooks de forma assíncrona. Responda com
200 imediatamente e processe o evento em background. Se seu handler demorar mais de 20 segundos, a Chargefy considerará a entrega como falhada.Idempotência
Idempotência
Use o
webhook-id (ou o campo id no JSON do corpo, quando presente — mesmo valor) como chave de idempotência. O mesmo evento pode ser entregue mais de uma vez (retry). Garanta que processar o mesmo evento duas vezes não cause efeitos duplicados.Sempre verifique a assinatura
Sempre verifique a assinatura
Nunca processe um webhook sem verificar a assinatura HMAC. Isso protege contra requisições forjadas.
Monitore entregas no dashboard
Monitore entregas no dashboard
Acompanhe o status das entregas em Configurações → Webhooks → Entregas. Verifique regularmente se há falhas persistentes.
Use HTTPS
Use HTTPS
URLs de webhook devem usar HTTPS. A Chargefy não aceita endpoints HTTP.
Desenvolvimento Local
Para testar webhooks em desenvolvimento local, use um tunnel:Troubleshooting
| Problema | Causa Provável | Solução |
|---|---|---|
| Status 401 | Assinatura inválida | Verifique se está usando o secret correto e raw body |
| Status 500 | Erro no seu handler | Verifique logs da sua aplicação |
| Timeout | Handler muito lento | Processe em background, responda com 200 imediatamente |
| Não recebe webhooks | URL incorreta ou firewall | Verifique URL (HTTPS), teste com curl |
| Webhook duplicado | Retry após falha anterior | Implemente idempotência com webhook-id |
Próximos Passos
Eventos Disponíveis
Lista completa de 27 tipos de eventos
Gerenciar Endpoints
Criar, atualizar e deletar endpoints

