Tentativas e cabeçalhos
Cada evento vira uma entrega por endpoint. Se o seu servidor não confirma, a plataforma tenta de novo, até 9 vezes em cerca de 3 dias.
Cabeçalhos de cada entrega
| Cabeçalho | Valor |
|---|---|
Content-Type | application/json |
User-Agent | AveroPay-Webhooks/1.0 |
X-Signature | t=<unix>,v1=<hex>: a assinatura (veja Verificar X-Signature). |
X-Event-Id | O id do evento (evt_…), igual ao id do corpo. O mesmo em todas as tentativas e reenvios: use para deduplicar. |
X-Event-Type | O tipo, igual ao type do corpo. |
X-Delivery-Id | A entrega deste evento a este endpoint (whd_…). O mesmo em todas as tentativas dela. |
X-Delivery-Attempt | O número da tentativa: 1 na primeira. |
O que conta como recebido
- Resposta 2xx em até 10 segundos. O corpo da resposta é ignorado (o painel mostra o começo dele).
- Qualquer outra coisa é falha: 3xx (redirecionamento não é seguido), 4xx, 5xx, demora acima de 10 segundos ou conexão recusada.
- URL que deixou de ser https pública falha sem novas tentativas. Veja Regras da URL.
Novas tentativas
A primeira tentativa sai logo depois do evento. Depois de cada falha, a próxima espera:
- 2ª1 min
- 3ª5 min
- 4ª30 min
- 5ª2 h
- 6ª6 h
- 7ª12 h
- 8ª24 h
- 9ª24 h
São 9 tentativas em cerca de 3 dias. Se a última falhar, a entrega fica como falha definitiva e não há mais tentativas automáticas.
Reenviar pelo painel
Em Desenvolvedores › Webhooks, cada entrega mostra as tentativas e as respostas. "Reenviar" manda de novo na hora: numa entrega encerrada (entregue ou falha definitiva), é uma tentativa só; numa que ainda está tentando, o calendário segue depois dela.
Deduplicar e ordenar
- A entrega é "pelo menos uma vez": o mesmo evento pode chegar de novo (um reenvio, ou uma resposta 2xx que se perdeu). Guarde os
X-Event-Idjá tratados e ignore os repetidos. - A ordem não é garantida: uma entrega que falhou chega depois de eventos mais novos. Use o status em data e o createdAt do evento, ou consulte o recurso pela API.
- Com mais de um endpoint no mesmo grupo, cada um recebe a sua entrega, com X-Delivery-Id próprio e o mesmo X-Event-Id.
Responda 2xx assim que guardar o evento e processe depois. Processar dentro da requisição e passar de 10 segundos faz o evento voltar, e você o trata duas vezes se não deduplicar.