Skip to main content
Uma cobrança enviada duas vezes é um problema jurídico, não só um custo. Se a sua chamada cair na rede, você fica sem saber se ela chegou. A Idempotency-Key resolve isso: você repete, e o Pombo reconhece a repetição, devolve a notificação original e não envia de novo. O cabeçalho é opcional, mas vale mandar sempre. Sem ele, cada chamada cria uma notificação nova: se você repetir uma requisição cuja resposta não chegou, o destinatário recebe duas notificações e você paga dois envios. E não há como desfazer, porque uma notificação extrajudicial emitida não pode ser cancelada.

​
Como usar

Envie o cabeçalho em POST /notifications. Uma chave por notificação, gerada por você, estável entre as tentativas. Letras, dígitos, sublinhados e hifens, até 255 caracteres; qualquer outro caractere devolve 400.
A diferença entre 201 e 200 é o sinal mais barato que existe: um 200 significa que nada novo foi criado e nenhum envio foi descontado. Com anexo, o arquivo entra na conta. Dois documentos diferentes sob a mesma chave nunca podem ser confundidos com a mesma notificação, por isso o segundo é 409 e não uma repetição. A resposta traz idempotency_key, a chave que você enviou. O resumo do pedido não é devolvido: o Pombo guarda um sha256 do envio internamente e é com ele que decide entre devolver a original e recusar com 409. É um detalhe de deduplicação, não parte do contrato.
A Idempotency-Key vale só em POST /notifications. Em POST /templates o cabeçalho é ignorado, e repetir a chamada cria um segundo modelo: o Pombo renomeia o nome repetido sozinho, acrescentando -2, -3, em vez de recusar o conflito.Como a API não lista modelos, esse segundo modelo fica inalcançável: você não recebeu o template_id dele e não há como consultá-lo depois. Se a resposta de POST /templates não chegar, não repita às cegas. Em WhatsApp o modelo duplicado ainda vai para aprovação da Meta.

​
Quando tentar de novo

Um 500 em POST /notifications não garante que nada foi enviado, e é justamente por isso que repetir com a mesma chave é seguro: se o envio já tinha acontecido, você recebe a notificação original em vez de uma segunda. Repetir um 4xx sem mudar nada só gasta requisição. A resposta diz o que corrigir, e a lista está em Erros. Para repetir um envio que falhou, use uma chave nova. A chave é gravada uma única vez e nunca é liberada, então reaproveitá-la devolve a falha original em vez de tentar de novo. Uma repetição idempotente também não desconta nada: ela não cria uma notificação, devolve a que já existia.