Idempotência

Em sistema distribuído, repetir é o jeito normal de se recuperar de uma falha: o timeout não diz se a outra ponta processou ou não, e a única saída segura é tentar de novo. Idempotência é o que faz a repetição não virar duplicata.

A pergunta aparece em três direções no Notyfacil, e cada uma tem o seu mecanismo.

Quando você publica: Idempotency-Key

A sua chamada a POST /v1/events deu timeout. O evento foi gravado ou não? Não dá para saber, e publicar de novo sem proteção cria um segundo pedido.pago, com uma segunda leva de entregas.

Mande o header Idempotency-Key:

curl -X POST https://api.notyfacil.com.br/v1/events \
  -H "Authorization: Bearer $NOTYFACIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-1234-pago" \
  -d '{"consumer":"cliente-42","type":"pedido.pago","data":{"pedidoId":1234}}'

A primeira chamada responde 202 e publica. Qualquer repetição com a mesma chave responde 200, com o header Idempotency-Replayed: true e o mesmo id, sem publicar nada de novo, mesmo que as duas chamadas cheguem ao mesmo tempo.

Três regras:

• A chave vale para sempre dentro do ambiente. Não expira.
• Derive a chave do fato, não da tentativa. pedido-1234-pago é boa: o mesmo fato gera sempre a mesma chave. Um UUID novo a cada tentativa não protege nada.
• A repetição não compara o corpo. Mesma chave com data diferente devolve o evento original, e o data novo é descartado. Fato diferente pede chave diferente.

A chave tem até 200 caracteres. Ela também pode ir no campo idempotencyKey do corpo; se os dois vierem, o header vale.

Quando nós entregamos: Webhook-Id

Do nosso lado para o receptor, a garantia é ao menos uma vez: o mesmo webhook pode chegar duas vezes. Todo webhook leva o header Webhook-Id, estável entre as tentativas e igual no replay, e quem recebe deduplica por ele.

A receita completa, com tabela e código, está em deduplicação e ordem.

Quando um provedor reenvia: o id do evento do provedor

No recebimento, quem repete é o provedor: o Mercado Pago não recebeu o nosso 202 a tempo e manda a mesma notificação de novo. Quando o provedor identifica os eventos dele, a fonte reconhece a repetição: responde ao provedor com a mesma mensagem da primeira vez e não cria entregas novas para os seus destinos.

Nota

Nem todo provedor manda um id de evento. Quando não manda, cada chegada é uma mensagem nova, e a deduplicação volta a ser do seu lado, pelo Webhook-Id que o repasse carrega.