Business OS · Documentação

#Entrega, retries e idempotência

Esta página reúne as regras de funcionamento que valem para todo evento.

#O que responder

Sua respostaO que fazemos
Qualquer 2xx (200, 201, 202, 204)Entrega concluída. Não repetimos.
410 GoneDesligamos 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ãoFalha. Tentamos de novo mais tarde.

Pontos que pegam desprevenido:

#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):

TentativaEspera 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:

O delivery.kind diz por que o envio aconteceu:

kindSignificado
firstPrimeiro envio.
auto_retryNova tentativa automática depois de falha.
manual_redeliveryAlguém da equipe mandou reenviar.
period_redeliveryReenvio em lote de um período.
manual_testAviso 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:

#Datas e fuso

#Dinheiro

#Campos nulos e campos novos

#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

  1. Responda 2xx em menos de 15 s.
  2. Guarde o webhook-id e ignore repetidos.
  3. Não confie na ordem.
  4. Confira a assinatura com o corpo cru.
  5. Valores em centavos, datas em UTC.
  6. Ignore campos que você não conhece.
  7. Escolha UM fluxo para decidir acesso.

← Assinatura e segurança  ·  Liberar conteúdo no pagamento aprovado →