Visão Geral de Webhooks

A A55 envia um HTTP POST webhook para sua webhook_url sempre que o status de uma cobrança muda, oferecendo visibilidade em tempo real sobre os pagamentos.

Por que webhooks

Aspecto	Webhooks (push)	Polling (pull)
Latência	Segundos	Minutos (depende do intervalo)
Confiabilidade	Entrega garantida com retentativas	Eventos perdidos entre intervalos
Carga no servidor	Orientado a eventos, mínima	Requisições constantes independente de atividade

Configuração

Defina webhook_url em cada requisição de cobrança, ou configure uma URL padrão no dashboard da A55.

Configuração	Descrição
webhook_url por cobrança	Define na requisição — recebe eventos apenas daquela cobrança
URL padrão no dashboard	Usada quando webhook_url é omitida

Propriedade	Valor
Método	POST
Content-Type	application/json
Timeout	30 segundos
TLS	Somente HTTPS

Política de retentativas

Entregas com falha são retentadas com backoff exponencial ao longo de 24 horas:

Tentativa	Atraso	Acumulado
1	Imediata	T+0
2	1 minuto	T+1m
3	5 minutos	T+6m
4	30 minutos	T+36m
5	2 horas	T+2h 36m
6	6 horas	T+8h 36m
7	24 horas	T+32h 36m

Após 7 tentativas falhadas, o evento é marcado como falha no dashboard.

Resposta	Retenta?
2xx	Não — entregue com sucesso
4xx	Não — erro permanente do cliente
5xx	Sim — erro transiente do servidor
Timeout (>30 s)	Sim
Conexão recusada	Sim

Idempotência

Webhooks usam entrega at-least-once. O mesmo evento pode chegar mais de uma vez. Seu handler deve ser idempotente — deduplique por charge_uuid.

Responda rapidamente

Retorne 200 OK imediatamente ao receber o webhook. Processe o evento em um job de background para evitar timeouts e entregas duplicadas.

Testes

Ferramenta	Uso
webhook.site	Inspecionar payloads sem rodar um servidor
ngrok	Expor servidor local para webhooks do sandbox
A55 sandbox	Enviar eventos de teste reais no ambiente sandbox