Uma integração de pagamento pode funcionar bem durante meses e, ainda assim, falhar quando o volume cresce. Basta um evento duplicado, uma resposta lenta ou uma indisponibilidade temporária para criar cobranças repetidas, pedidos sem baixa e divergências financeiras.

Esse problema não ocorre porque os webhooks são pouco confiáveis. Ele aparece quando a arquitetura parte de uma premissa incorreta: a de que cada evento chegará uma única vez, na ordem certa e no momento esperado.

Em sistemas distribuídos, atrasos, repetições e falhas de comunicação são normais. Por isso, webhooks e idempotência precisam ser tratados como partes do mesmo projeto.

O webhook informa que algo aconteceu. A idempotência garante que o mesmo evento possa ser recebido ou processado novamente sem repetir seu efeito financeiro.

Uma integração resiliente não tenta impedir todas as falhas. Ela é construída para reconhecer, absorver e corrigir falhas sem perder o controle da transação.

Por que integrações de pagamento perdem transações?

Uma transação percorre diversos sistemas. O checkout envia uma solicitação ao provedor. O provedor autoriza o pagamento. Depois, outro evento confirma a captura, a liquidação, o estorno ou uma contestação.

Cada etapa depende de rede, aplicações, bancos de dados e serviços externos. Uma falha em qualquer ponto pode interromper a comunicação.

Entre os problemas mais comuns estão:

• o provedor envia o evento, mas a aplicação está indisponível;
• o servidor recebe o webhook, mas demora demais para responder;
• a resposta é perdida e o provedor envia o mesmo evento novamente;
• dois eventos chegam fora da ordem esperada;
• o sistema grava parte da operação e falha antes de concluir;
• uma chamada à API é repetida após um timeout;
• um evento inválido entra no fluxo sem validação de assinatura;
• uma mensagem falha várias vezes e desaparece sem gerar alerta.

Esses casos não são exceções raras. Eles fazem parte da operação normal de um sistema distribuído.

Por isso, uma integração não deve depender da ideia de entrega única. O modelo mais realista é o de entrega at least once, ou seja, pelo menos uma vez.

Nesse modelo, o evento pode chegar novamente. A aplicação precisa estar preparada para reconhecer a repetição.

O que são webhooks e idempotência?

Um webhook é uma requisição enviada por um sistema quando determinado evento ocorre. Em pagamentos, ele pode informar que uma cobrança foi aprovada, recusada, liquidada, cancelada ou estornada.

Em vez de consultar a API do provedor a cada poucos segundos, a empresa recebe uma notificação quando há uma mudança relevante.

A idempotência é a propriedade que permite executar a mesma operação mais de uma vez sem alterar o resultado após a primeira execução válida.

Considere um evento que confirma o pagamento de um pedido. Se ele chegar três vezes, a aplicação pode registrar três recebimentos ou liberar três créditos ao cliente.

Em uma operação idempotente, as três entregas produzem apenas um efeito:

• o pedido é marcado como pago uma única vez;
• o saldo é creditado uma única vez;
• a nota fiscal é solicitada uma única vez;
• o acesso ao serviço é liberado uma única vez.

A documentação da MDN explica a idempotência no contexto de requisições HTTP. Porém, em pagamentos, a proteção precisa existir também na regra de negócio.

Deduplicação e idempotência não são a mesma coisa

Os dois conceitos estão relacionados, mas não são idênticos.

A deduplicação identifica que uma mensagem já foi recebida. A idempotência garante que uma operação repetida não produza um novo efeito.

Registrar o identificador de cada evento ajuda a bloquear uma entrega duplicada. Porém, isso não resolve todos os cenários.

Um provedor pode gerar dois eventos diferentes relacionados à mesma operação. Nesse caso, cada evento terá seu próprio identificador, mas ambos poderão tentar executar a mesma ação interna.

Por isso, uma integração robusta precisa proteger dois níveis:

1. Nível do evento: impede o processamento repetido do mesmo webhook.
2. Nível da operação: impede que eventos diferentes repitam o mesmo efeito financeiro.

Por que webhooks podem chegar duplicados?

Quando um provedor envia um webhook, ele espera uma resposta de sucesso. Em geral, essa resposta usa um código HTTP da família 2xx.

Imagine que a aplicação processe o evento, atualize o pedido e responda com sucesso. Porém, a conexão é interrompida antes que o provedor receba a resposta.

Para o provedor, a entrega não foi confirmada. Portanto, ele tenta novamente.

O resultado é uma segunda entrega de um evento que já produziu efeito.

Esse comportamento é esperado. A própria documentação de webhooks da Stripe, por exemplo, orienta as integrações a tratar eventos duplicados e a não depender da ordem de entrega.

O erro não está no retry do provedor. O erro está em criar uma operação que não suporta retry.

Arquitetura recomendada para webhooks e idempotência

O endpoint de webhook não deve concentrar todo o processamento. Sua principal função é validar, registrar e encaminhar o evento para um fluxo assíncrono.

Uma arquitetura segura pode seguir esta sequência:

1. Receber a requisição.
2. Validar a assinatura do provedor.
3. Extrair os metadados básicos do evento.
4. Persistir o conteúdo em uma área durável.
5. Identificar entregas duplicadas.
6. Encaminhar o evento para uma fila.
7. Responder rapidamente com um código 2xx.
8. Processar a regra de negócio em segundo plano.
9. Registrar sucesso, falha ou necessidade de retry.

Esse desenho reduz o tempo de resposta do endpoint e separa o recebimento da execução da regra de negócio.

Fluxo recomendado

Provedor de pagamento
        |
        | POST /webhooks
        v
Validação de assinatura
        |
        v
Tabela de eventos recebidos
        |
        | evento novo
        v
Fila de processamento
        |
        v
Worker idempotente
        |
        +----> Pedido
        +----> Assinatura
        +----> Conciliação
        +----> Notificação
        |
        | falha após tentativas
        v
Dead letter queue

A tabela de eventos recebidos também é chamada de inbox. Ela funciona como uma caixa de entrada durável para integrações assíncronas.

O evento só deve receber confirmação depois de ter sido gravado de forma segura. Caso a aplicação responda antes da persistência e falhe em seguida, o webhook poderá ser perdido.

Como implementar idempotência no recebimento do webhook?

A primeira camada de idempotência deve usar o identificador fornecido pelo provedor.

Uma tabela simples pode armazenar:

• nome do provedor;
• identificador do evento;
• tipo do evento;
• identificador do objeto financeiro;
• conteúdo original;
• data de recebimento;
• status de processamento;
• número de tentativas;
• último erro registrado.

Crie uma restrição única para a combinação entre provedor e identificador do evento.

CREATE TABLE payment_events (
    id BIGSERIAL PRIMARY KEY,
    provider VARCHAR(50) NOT NULL,
    event_id VARCHAR(255) NOT NULL,
    event_type VARCHAR(120) NOT NULL,
    object_id VARCHAR(255),
    payload JSONB NOT NULL,
    status VARCHAR(30) NOT NULL DEFAULT 'received',
    attempts INTEGER NOT NULL DEFAULT 0,
    received_at TIMESTAMP NOT NULL DEFAULT NOW(),
    processed_at TIMESTAMP,
    last_error TEXT,
    UNIQUE (provider, event_id)
);

Se a inserção violar a restrição única, o evento já foi recebido. O endpoint pode responder com sucesso sem executar novamente a operação.

Essa proteção evita a repetição do mesmo evento, mas ainda é necessário proteger a regra de negócio.

Exemplo de recebimento idempotente

async function receiveWebhook(request, response) {
    const rawBody = request.rawBody;
    const signature = request.headers["payment-signature"];

    const event = verifyAndParseWebhook(rawBody, signature);

    try {
        await database.paymentEvents.insert({
            provider: "payment-provider",
            eventId: event.id,
            eventType: event.type,
            objectId: event.data.object.id,
            payload: event
        });
    } catch (error) {
        if (error.code === "UNIQUE_VIOLATION") {
            return response.status(200).send("Evento já recebido");
        }

        return response.status(500).send("Falha ao persistir evento");
    }

    await queue.publish({
        provider: "payment-provider",
        eventId: event.id
    });

    return response.status(200).send("Evento recebido");
}

O exemplo é simplificado. Em produção, a gravação do evento e sua publicação na fila precisam evitar um problema conhecido como dual write.

Como evitar falhas entre o banco de dados e a fila?

Considere este cenário:

1. o evento é salvo no banco;
2. a aplicação tenta publicar a mensagem na fila;
3. a fila está indisponível;
4. o endpoint retorna erro;
5. o provedor repete o evento;
6. a restrição única identifica a duplicidade;
7. a aplicação responde com sucesso sem publicar a mensagem.

O evento ficou salvo, mas nunca chegou ao processador.

Esse é um exemplo de falha de escrita dupla. A aplicação tentou atualizar dois sistemas independentes sem uma transação comum.

Existem duas soluções frequentes:

• Transactional outbox: a aplicação salva o evento e um registro de publicação na mesma transação do banco.
• Banco como fila inicial: um processo consulta os eventos pendentes e os encaminha ao worker.

Padrão transactional outbox

No padrão transactional outbox, a aplicação grava o evento e a mensagem que deverá ser publicada dentro da mesma transação.

BEGIN;

INSERT INTO payment_events (
    provider,
    event_id,
    event_type,
    payload
) VALUES (
    'payment-provider',
    'evt_123',
    'payment.approved',
    '{...}'
);

INSERT INTO outbox_messages (
    topic,
    reference_id,
    payload
) VALUES (
    'payment-events',
    'evt_123',
    '{"event_id":"evt_123"}'
);

COMMIT;

Um processo separado lê a tabela de outbox e publica as mensagens na fila. Depois, marca cada registro como enviado.

Se a publicação falhar, o registro permanece disponível para uma nova tentativa.

Idempotência na regra de negócio

O worker não deve confiar apenas no identificador do webhook. Ele também precisa verificar se o efeito financeiro já ocorreu.

Imagine dois eventos:

• payment.approved;
• invoice.paid.

Os dois podem indicar, dentro de determinado fluxo, que o pedido deve ser marcado como pago.

Se cada handler executar a baixa sem verificar o estado atual, o mesmo pedido poderá gerar efeitos duplicados.

Uma proteção simples é usar uma transição condicional:

UPDATE orders
SET
    payment_status = 'paid',
    paid_at = NOW()
WHERE
    id = :order_id
    AND payment_status != 'paid';

Depois, a aplicação verifica quantas linhas foram alteradas.

• Se uma linha foi alterada, a transição ocorreu.
• Se nenhuma linha foi alterada, o pedido já estava pago.

Outra opção é criar uma tabela de operações financeiras com uma chave única de negócio.

CREATE TABLE financial_operations (
    id BIGSERIAL PRIMARY KEY,
    operation_key VARCHAR(255) NOT NULL UNIQUE,
    order_id BIGINT NOT NULL,
    operation_type VARCHAR(80) NOT NULL,
    amount NUMERIC(15, 2) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

A chave pode combinar o pedido com a operação:

order:78452:confirm-payment

Mesmo que eventos diferentes tentem confirmar o mesmo pagamento, apenas uma operação será criada.

Como usar chaves de idempotência em chamadas de API?

A idempotência também é necessária quando sua aplicação envia comandos ao provedor.

Considere a criação de uma cobrança. A aplicação envia a requisição, mas ocorre um timeout. Não é possível saber se o provedor criou ou não a transação.

Repetir a chamada sem proteção pode criar duas cobranças.

A solução é enviar uma chave de idempotência que represente a operação de negócio.

POST /payments
Idempotency-Key: subscription:9012:invoice:2026-08

{
    "amount": 19990,
    "currency": "BRL",
    "customer_id": "customer_845"
}

A chave deve permanecer igual em todas as tentativas da mesma operação.

Não gere uma nova chave a cada retry. Caso isso ocorra, o provedor interpretará cada chamada como uma nova solicitação.

A documentação de requisições idempotentes da Stripe apresenta um exemplo desse mecanismo.

A estratégia exata varia entre provedores. Por isso, verifique:

• quais endpoints aceitam a chave;
• por quanto tempo ela é armazenada;
• qual é o limite de caracteres;
• como o provedor trata parâmetros diferentes com a mesma chave;
• se a resposta original é preservada;
• como erros são armazenados e retornados.

Webhooks e idempotência precisam de processamento assíncrono

Executar toda a regra de negócio dentro do endpoint aumenta o risco de timeout.

O processo pode envolver:

• consulta ao banco de dados;
• atualização de pedido;
• criação de nota fiscal;
• envio de e-mail;
• atualização do ERP;
• registro contábil;
• liberação de acesso;
• chamada a outro serviço externo.

Se qualquer etapa demorar, o provedor poderá considerar a entrega malsucedida e reenviar o evento.

O endpoint deve validar e armazenar o webhook. O restante deve ser processado por workers em segundo plano.

Essa separação permite controlar concorrência, retry e prioridade. Também evita que um pico de eventos derrube o endpoint público.

Como implementar retry exponencial?

Quando uma operação falha por um problema temporário, ela pode ser repetida.

Porém, repetir imediatamente e sem limite pode agravar a indisponibilidade. Centenas de workers podem atacar um serviço que já está sobrecarregado.

O retry exponencial aumenta o intervalo entre as tentativas.

Um exemplo simples seria:

• primeira repetição após 2 segundos;
• segunda repetição após 4 segundos;
• terceira repetição após 8 segundos;
• quarta repetição após 16 segundos;
• quinta repetição após 32 segundos.

A fórmula básica pode ser representada assim:

intervalo = min(limite_máximo, intervalo_base × 2^tentativa)

Também é recomendado adicionar jitter, uma variação aleatória no intervalo.

intervalo_final = random(0, intervalo_calculado)

O jitter evita que vários processos façam novas tentativas no mesmo instante.

A documentação do Google Cloud sobre estratégias de retry recomenda backoff exponencial com jitter para operações que possam ser repetidas com segurança.

Quais erros devem ser repetidos?

Nem toda falha é temporária.

Tipo de falha	Exemplos	Ação recomendada
Falha transitória	Timeout, conexão interrompida, HTTP 408, 429 ou 5xx	Aplicar retry com backoff
Falha permanente	Payload inválido, credencial incorreta, recurso inexistente	Interromper retry e gerar alerta
Falha de regra de negócio	Transição inválida, valor divergente, pedido cancelado	Registrar para análise
Falha desconhecida	Erro não classificado	Limitar tentativas e enviar para DLQ

Ao receber um código 429, a aplicação também deve respeitar o cabeçalho Retry-After, quando ele estiver disponível.

Retries sem classificação podem ocultar erros permanentes e consumir recursos durante horas.

O que é uma dead letter queue?

Uma DLQ é uma fila destinada a mensagens que não puderam ser processadas após determinado número de tentativas.

Ela impede que uma mensagem com erro permanente bloqueie o restante da fila.

A DLQ também preserva o evento para análise e reprocessamento.

Um registro enviado para a dead letter queue deve conter:

• identificador do evento;
• conteúdo original;
• tipo do evento;
• data da primeira tentativa;
• data da última tentativa;
• quantidade de tentativas;
• erro mais recente;
• serviço que apresentou a falha;
• dados de correlação e rastreamento.

A documentação da AWS sobre dead letter queues destaca o uso da DLQ para isolar mensagens não processadas, analisar falhas e executar o redrive.

A DLQ não pode virar um arquivo morto

Criar uma dead letter queue sem monitoramento apenas muda o local onde as transações são perdidas.

Uma operação madura deve:

• gerar alerta quando uma mensagem entrar na DLQ;
• registrar o motivo da falha;
• definir responsáveis pela análise;
• permitir correção e reprocessamento;
• manter histórico do redrive;
• acompanhar a idade da mensagem mais antiga;
• definir prazo máximo de resolução.

A retenção da DLQ deve ser maior que a retenção da fila de origem. Caso contrário, a mensagem poderá expirar antes de ser analisada.

Como tratar eventos fora de ordem?

Uma integração não deve assumir que os eventos chegarão na sequência em que ocorreram.

Um evento de pagamento liquidado pode chegar antes do evento de autorização. Um estorno pode ser recebido antes de um worker concluir o processamento do pagamento original.

Para reduzir esse risco, use uma máquina de estados.

Por exemplo:

pending
   |
   v
authorized
   |
   v
captured
   |
   v
settled
   |
   +----> refunded
   |
   +----> disputed

Cada transição deve ser validada. O sistema não deve voltar um pagamento liquidado para o estado “pendente” apenas porque recebeu um evento antigo.

Entre as estratégias possíveis estão:

• comparar a versão do objeto;
• consultar o estado atual na API do provedor;
• usar o horário do evento com cautela;
• definir transições monotônicas;
• bloquear atualizações que representem regressões inválidas;
• agrupar o processamento pela chave da transação.

O horário de recebimento não indica, necessariamente, a ordem real dos eventos.

Polling ainda tem utilidade?

Depender apenas de polling pode aumentar latência, custo e consumo da API. Porém, isso não significa que toda consulta periódica seja inadequada.

Webhooks e polling cumprem funções diferentes:

• Webhooks: oferecem atualização rápida e orientada a eventos.
• Polling de reconciliação: verifica se algum evento foi perdido ou permaneceu sem processamento.

Uma arquitetura robusta usa o webhook como canal principal e um processo periódico como mecanismo de verificação.

Por exemplo, a cada hora o sistema pode buscar transações alteradas no provedor e compará-las com os registros internos.

Esse processo detecta:

• eventos que não chegaram;
• eventos recebidos, mas não processados;
• status divergentes;
• liquidações sem correspondência;
• estornos ainda não refletidos;
• falhas de conciliação.

Veja também o conteúdo sobre conciliação automática e visibilidade financeira em tempo real.

Segurança no recebimento de webhooks

Um endpoint público pode receber requisições de qualquer origem. Por isso, não basta aceitar o conteúdo enviado.

A integração deve validar a assinatura criptográfica fornecida pelo provedor.

O processo costuma envolver:

1. receber o corpo original da requisição;
2. ler o cabeçalho de assinatura;
3. calcular ou validar a assinatura com o segredo configurado;
4. verificar a tolerância de tempo;
5. rejeitar mensagens inválidas;
6. registrar a tentativa sem expor dados sensíveis.

Alguns frameworks alteram o corpo antes da validação. Por isso, pode ser necessário preservar o raw body, ou corpo bruto, da requisição.

Outras medidas importantes incluem:

• usar TLS;
• rotacionar segredos;
• limitar o tamanho do payload;
• aplicar rate limiting com cuidado;
• não registrar credenciais ou dados sensíveis;
• separar endpoints por ambiente;
• validar o tipo e a versão do evento;
• manter trilha de auditoria.

Observabilidade para webhooks e idempotência

Uma integração pode continuar respondendo HTTP 200 enquanto deixa de atualizar pedidos. Por isso, disponibilidade do endpoint não é suficiente.

É necessário acompanhar indicadores de negócio e de infraestrutura.

Entre os principais KPIs estão:

• quantidade de eventos recebidos;
• percentual de eventos duplicados;
• latência entre criação e recebimento;
• latência entre recebimento e processamento;
• taxa de processamento com sucesso;
• quantidade de retries;
• eventos na DLQ;
• idade do evento pendente mais antigo;
• falhas de validação de assinatura;
• diferenças entre o provedor e a base interna;
• eventos por tipo e por versão;
• tempo médio para resolver falhas.

Use identificadores de correlação para conectar logs de diferentes sistemas.

Um registro pode incluir:

{
    "correlation_id": "corr_78451",
    "provider": "payment-provider",
    "event_id": "evt_123",
    "payment_id": "pay_456",
    "order_id": "order_789",
    "event_type": "payment.approved",
    "attempt": 2,
    "status": "processing"
}

Esse contexto facilita a investigação de uma transação específica.

Erros comuns em integrações com webhooks

1. Marcar o pedido como pago apenas pela resposta da API

A resposta de criação ou autorização não substitui a confirmação assíncrona. Dependendo do meio de pagamento, o status pode mudar depois.

2. Responder antes de persistir o evento

Se o servidor responder HTTP 200 e falhar antes da gravação, o provedor poderá considerar o evento entregue, embora a aplicação nunca o tenha armazenado.

3. Processar tudo de forma síncrona

Chamadas demoradas aumentam o risco de timeout e de entregas duplicadas.

4. Confiar apenas no identificador do webhook

Eventos diferentes podem tentar executar a mesma operação financeira. A regra de negócio também precisa ser idempotente.

5. Repetir todas as falhas

Erros permanentes não serão corrigidos com retry. Eles precisam de análise ou ajuste nos dados.

6. Criar uma nova chave de idempotência a cada tentativa

Uma chave nova transforma o retry em uma nova operação.

7. Assumir ordem de entrega

A chegada fora de ordem é possível. O estado deve ser validado antes de cada atualização.

8. Não manter rotina de reconciliação

Mesmo uma arquitetura bem construída precisa verificar se os registros internos correspondem ao estado do provedor.

9. Manter uma DLQ sem alertas

Mensagens podem ficar esquecidas até expirarem.

10. Ignorar mudanças de versão

Alterações no formato do evento podem quebrar parsers, validações e regras de negócio.

Como testar webhooks e idempotência antes da produção?

Testar apenas o caminho de sucesso não é suficiente.

O plano de testes deve incluir:

1. enviar o mesmo evento várias vezes;
2. enviar eventos relacionados fora de ordem;
3. simular timeout após uma operação bem-sucedida;
4. interromper o worker durante o processamento;
5. indisponibilizar temporariamente o banco;
6. indisponibilizar a fila;
7. enviar uma assinatura inválida;
8. alterar o formato do payload;
9. simular erro 429 e respeitar o Retry-After;
10. forçar o envio de uma mensagem para a DLQ;
11. executar o redrive após corrigir a falha;
12. comparar a base interna com os dados do provedor.

Também é importante verificar o efeito final.

Receber o mesmo evento dez vezes deve produzir:

• uma única baixa financeira;
• uma única liberação de acesso;
• uma única emissão fiscal;
• uma única atualização de saldo;
• um histórico completo das dez entregas ou tentativas.

Checklist para integrações de pagamento resilientes

• Validar a assinatura de todos os webhooks.
• Preservar o corpo bruto quando o provedor exigir.
• Persistir o evento antes de responder com sucesso.
• Criar uma restrição única por provedor e evento.
• Processar eventos de forma assíncrona.
• Proteger a regra de negócio com chaves únicas.
• Usar idempotency keys em comandos enviados à API.
• Manter a mesma chave durante os retries.
• Aplicar retry exponencial com jitter.
• Separar falhas transitórias de falhas permanentes.
• Definir limite de tentativas.
• Enviar mensagens não processadas para uma DLQ.
• Criar alertas e fluxo de redrive.
• Tratar eventos fora de ordem.
• Executar reconciliação periódica.
• Monitorar métricas técnicas e financeiras.
• Testar duplicidade, timeout e indisponibilidade.

Como a ExPay apoia integrações de pagamento?

Construir e manter integrações separadas para Pix, cartão, boleto, assinaturas e conciliação aumenta o número de eventos, formatos e regras que a empresa precisa controlar.

A ExPay oferece uma camada unificada de infraestrutura de pagamentos. Com uma única integração, empresas digitais podem organizar diferentes meios de pagamento e centralizar eventos operacionais.

Essa abordagem reduz a fragmentação entre checkout, cobrança, conciliação e sistemas internos.

Uma infraestrutura unificada não elimina a necessidade de webhooks e idempotência. Porém, reduz o número de integrações isoladas que precisam implementar esses controles de forma independente.

Conheça as soluções de infraestrutura de pagamentos da ExPay ou acesse outros conteúdos técnicos no Blog ExPay.

Webhooks e idempotência são requisitos financeiros

Webhooks e idempotência não devem ser tratados apenas como detalhes de desenvolvimento.

Um evento duplicado pode gerar cobrança indevida. Um evento perdido pode manter um cliente inadimplente mesmo após o pagamento. Uma falha de ordem pode reabrir uma fatura já liquidada.

Esses problemas afetam receita, conciliação, atendimento e confiança do cliente.

Uma integração robusta deve assumir que eventos podem atrasar, repetir, falhar ou chegar fora de ordem. A arquitetura precisa manter os efeitos financeiros sob controle mesmo nesses cenários.

Isso exige persistência durável, processamento assíncrono, idempotência de negócio, retry exponencial, dead letter queues e reconciliação periódica.

O objetivo não é garantir que cada mensagem seja entregue exatamente uma vez. O objetivo é garantir que cada operação financeira produza o efeito correto uma única vez.

Quando webhooks e idempotência são implementados dessa forma, a integração deixa de depender do caminho ideal e passa a suportar as falhas inevitáveis de uma operação em escala.

Para avaliar a infraestrutura de pagamentos da sua empresa, fale com a equipe ExPay.