17/05/2026 · Equipe GálagoTEF

Webhooks de pagamento: como usar para confirmar vendas

Um webhook é a forma mais eficiente de o seu sistema saber, em tempo real, que uma venda foi aprovada, negada ou estornada, sem ficar perguntando à API o tempo todo. Bem implementado, ele confirma vendas na hora e libera o pedido automaticamente. Mal implementado, ele vira fonte de venda duplicada e pedido liberado à toa. Este guia mostra como fazer certo.

O que é um webhook de pagamento

Webhook é uma notificação HTTP que a plataforma de pagamento envia para uma URL sua sempre que algo acontece com uma transação. Em vez de o seu sistema perguntar “e aí, aprovou?” repetidamente, a plataforma avisa assim que o status muda. É o oposto do polling, onde você consulta ativamente. Na prática, os dois se complementam: o webhook dá velocidade; o polling dá garantia caso uma notificação se perca.

O fluxo típico

1. Seu sistema cria uma transação e informa (ou pré-configura) a URL de webhook.
2. O cliente paga na maquininha; a administradora processa.
3. A plataforma envia um POST para a sua URL com o novo status e os dados da transação.
4. Seu sistema valida a assinatura, atualiza o pedido e responde 200.

Esse fluxo depende de você já ter uma boa integração de base. Se ainda está montando a sua, comece por como integrar a maquininha ao seu sistema.

Regras de ouro para consumir webhooks

Consumir webhook parece simples, mas alguns cuidados são obrigatórios em pagamento:

• Valide a assinatura. A plataforma assina o corpo da notificação com um segredo compartilhado. Sempre confira a assinatura antes de confiar no conteúdo; caso contrário, qualquer um pode forjar uma “venda aprovada”.
• Seja idempotente. A mesma notificação pode chegar mais de uma vez. Guarde o ID do evento e ignore duplicatas para não liberar o pedido duas vezes. Entenda melhor em idempotência em pagamentos.
• Responda rápido. Retorne 200 o mais cedo possível e processe o trabalho pesado de forma assíncrona. Webhooks costumam ter timeout curto.
• Trate retries. Se você não responder 200, a plataforma reenvia. Seu handler precisa aguentar reprocessar sem efeito colateral.
• Não confie só na ordem. Notificações podem chegar fora de ordem. Use o status recebido, não a sequência de chegada, para decidir o estado final.

Segurança do endpoint

O endpoint de webhook é uma porta de entrada pública, então trate-o como tal:

• Aceite apenas HTTPS.
• Valide a assinatura antes de qualquer processamento.
• Considere restringir por IP quando a plataforma publicar sua faixa.
• Nunca exponha dados sensíveis de cartão no seu log ao registrar o payload.

Por que ainda precisar de polling

Webhook é ótimo, mas depende da sua URL estar no ar. Se o seu servidor cair por cinco minutos, você pode perder notificações. Por isso, uma integração robusta combina os dois:

• Webhook para reação imediata na maioria das vendas.
• Polling para reconciliar transações cujo webhook não chegou, consultando o status pendente após alguns minutos.

Essa redundância é o que garante que nenhuma venda fique “no limbo”. Se você ainda está escolhendo a plataforma, veja o que priorizar em API de pagamento: o que avaliar antes de integrar.

Erros comuns

• Liberar o pedido em um status intermediário (pendente) em vez de esperar o final.
• Confiar na notificação sem validar a assinatura.
• Processar o mesmo evento duas vezes por falta de idempotência.
• Não ter fallback de polling e perder vendas quando o endpoint cai.

Confirme vendas com segurança e em tempo real

Webhook bem feito é o que transforma pagamento em algo automático: o cliente paga, a maquininha captura e o pedido é liberado sozinho, tudo em segundos. A diferença entre confiável e caótico está nos detalhes: assinatura, idempotência e um fallback de polling.

O GálagoTEF envia webhooks assinados para cada mudança de status e mantém a consulta por polling como rede de segurança. Veja o formato dos eventos na documentação da API e configure suas notificações em app.galagotef.com.br.

← Voltar ao blog