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çalhos da entrega
CabeçalhoValor
Content-Typeapplication/json
User-AgentAveroPay-Webhooks/1.0
X-Signaturet=<unix>,v1=<hex>: a assinatura (veja Verificar X-Signature).
X-Event-IdO id do evento (evt_…), igual ao id do corpo. O mesmo em todas as tentativas e reenvios: use para deduplicar.
X-Event-TypeO tipo, igual ao type do corpo.
X-Delivery-IdA entrega deste evento a este endpoint (whd_…). O mesmo em todas as tentativas dela.
X-Delivery-AttemptO 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:

  1. 2ª1 min
  2. 3ª5 min
  3. 4ª30 min
  4. 5ª2 h
  5. 6ª6 h
  6. 7ª12 h
  7. 8ª24 h
  8. 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-Id já 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.