#Entrega, retries e idempotência
Esta página reúne as regras de funcionamento que valem para todo evento.
#O que responder
| Sua resposta | O que fazemos |
|---|---|
Qualquer 2xx (200, 201, 202, 204) | Entrega concluída. Não repetimos. |
410 Gone | Desligamos o destino na hora. Use só se não quiser mais receber. |
Qualquer outro status (3xx, 4xx, 5xx) | Falha. Tentamos de novo mais tarde. |
| Sem resposta em 15 s, ou erro de conexão | Falha. Tentamos de novo mais tarde. |
Pontos que pegam desprevenido:
- Redirecionamento não é seguido. Um
301/302conta como falha. - Lemos no máximo 64 KB da sua resposta. O corpo da resposta não importa, só o status. Responda
okcurto. - Um
4xxtambém gera nova tentativa (exceto 410). Se você respondeu400por bug seu, o aviso volta depois, e isso é bom: corrija o bug e ele chega.
#Timeout: 15 segundos
Você tem 15 segundos para responder. Responda logo e processe depois (fila, tabela de tarefas). Se o processamento demora e você responde só no fim, o aviso será dado como falho e reenviado, e você vai processar duas vezes.
#Cronograma de retries
Quando uma entrega falha, tentamos de novo nestes intervalos (cada espera varia ±20% para não bater todos juntos):
| Tentativa | Espera antes dela |
|---|---|
| 2ª | 5 segundos |
| 3ª | 5 minutos |
| 4ª | 30 minutos |
| 5ª | 2 horas |
| 6ª | 5 horas |
| 7ª | 10 horas |
| 8ª | 10 horas |
| 9ª | 12 horas |
| 10ª | 12 horas |
| 11ª | 20 horas |
Somando, o aviso é insistido por cerca de 3 dias. Se o seu servidor responder com o cabeçalho Retry-After, esticamos a espera até o valor pedido, no máximo 24 horas.
Quando a insistência acaba:
- 5 dias seguidos só de falhas desligam o destino automaticamente. Depois disso nada é enviado até a equipe religar.
- Nos envios que voltam depois (reentrega manual, reentrega do período), o
delivery.kindmuda. Veja abaixo.
O delivery.kind diz por que o envio aconteceu:
kind | Significado |
|---|---|
first | Primeiro envio. |
auto_retry | Nova tentativa automática depois de falha. |
manual_redelivery | Alguém da equipe mandou reenviar. |
period_redelivery | Reenvio em lote de um período. |
manual_test | Aviso de teste, sempre com is_test: true. |
#Idempotência: o mesmo aviso pode chegar mais de uma vez
Ao menos uma vez é a garantia. Não é "exatamente uma". Por isso, seu código tem de dar o mesmo resultado se receber o mesmo aviso de novo.
O identificador é o webhook-id (o mesmo valor do delivery.message_id). Ele não muda entre as tentativas do mesmo aviso. Receita:
-- uma tabela com o id como chave única
CREATE TABLE processed_webhooks (id TEXT PRIMARY KEY, received_at TIMESTAMP);
-- ao receber: tente inserir. Se já existe, apenas responda 200.
INSERT INTO processed_webhooks (id, received_at) VALUES ($1, now())
ON CONFLICT (id) DO NOTHING;
-- se nenhuma linha foi inserida, é repetição: responda 200 e pare.
Faça a inserção e o trabalho na mesma transação, para que uma falha no meio não deixe o aviso "marcado como visto" sem ter sido processado.
Outra forma de ficar seguro é tornar a ação idempotente: "liberar o curso X para a pessoa Y" executada duas vezes termina igual.
#A ordem NÃO é garantida
Dois avisos enviados quase juntos podem chegar invertidos, e um aviso que falhou pode chegar depois de um mais novo. Exemplo real: payment.refunded pode chegar antes de payment.approved se o servidor de quem recebe demorou na primeira tentativa.
Como se proteger:
- Cada recurso tem
subject.sequence, um número que cresce a cada mudança daquele recurso. Guarde o maior que você já viu por recurso e descarte o aviso desequencemenor (ele é velho). - Use
occurred_atpara saber quando algo aconteceu, não a hora em que o aviso chegou. - Em dúvida sobre o estado atual do acesso, não deduza pela ordem: use os eventos
access.*(fluxokb_access) ou consulte a API de leitura.
#Datas e fuso
- Todas as datas são ISO 8601 em UTC, terminando em
Z(exemplo:2026-11-10T14:03:22.000Z). webhook-timestampé diferente: é segundos desde 1970, não texto.- Para mostrar na tela, converta para o fuso do usuário (Brasília é UTC-3). Não grave horário local.
- Em cada nova tentativa o corpo é remontado:
delivery.attemptedelivery.attempt_idmudam, o resto do fato é o mesmo. Por isso não use um hash do corpo como chave de idempotência; use owebhook-id.
#Dinheiro
- Valores em inteiros de centavos (
amount: 19700é R$ 197,00). Nunca ponto flutuante. - A moeda vem separada, em ISO 4217 (
BRL,USD).
#Campos nulos e campos novos
- Um campo
nullsignifica "não sabemos" ou "não se aplica". Trate com cuidado: não é zero nem texto vazio. - Campos novos podem aparecer a qualquer momento (é uma mudança compatível). Ignore o que você não conhece. Não rejeite um aviso por ter campo extra.
- Já mudar ou remover um campo existente é mudança incompatível e é anunciada no changelog.
#Um aviso, um fato. Duas coisas "parecidas" chegam juntas
Uma renovação paga gera dois avisos: payment.approved (o dinheiro entrou) e subscription.renewed (a assinatura renovou). Não conte duas vezes. Veja Renovação.
#Resumo em 7 linhas
- Responda 2xx em menos de 15 s.
- Guarde o
webhook-ide ignore repetidos. - Não confie na ordem.
- Confira a assinatura com o corpo cru.
- Valores em centavos, datas em UTC.
- Ignore campos que você não conhece.
- Escolha UM fluxo para decidir acesso.
← Assinatura e segurança · Liberar conteúdo no pagamento aprovado →