Webhooks
Webhooks de processamento de pagamentos, permitindo notificações HTTP em tempo real para sincronização entre mais de 50 parceiros adquirentes, automatizando a execução e acompanhando instantaneamente eventos de estorno ou atividade de MID.
- Categoria
- Programador
- Funcionalidades
- 6
- Disponível em
- Todos os planos
Os webhooks fornecem notificações em tempo real, impulsionadas por eventos, para atualizações críticas do ciclo de vida dos pagamentos. Os webhooks da Cardflo permitem que os seus sistemas reajam instantaneamente a estados de pagamento, disputas e outros eventos chave.
Automatize fluxos de trabalho e mantenha a sincronização entre a sua plataforma e a Cardflo sem sondagens constantes.
As notificações atempadas de webhooks fornecem atualizações em tempo real sobre o estado das transações e a atividade MID em toda a nossa extensa rede de adquirentes.
Este fluxo de dados instantâneo permite a automação rápida de processos de negócio críticos e respostas imediatas a eventos.
Visão geral de Webhooksgeral
Os webhooks funcionam como retornos de chamada HTTP assíncronos que facilitam a comunicação em tempo real entre uma gateway de pagamentos e um servidor comercial.
Ao contrário dos métodos tradicionais de sondagem, onde um servidor faz pedidos repetitivos para verificar atualizações de status, os webhooks enviam dados para um URL predefinido no momento em que um evento específico ocorre no ciclo de vida do pagamento.
Este mecanismo é crítico para gerir eventos não síncronos, como resultados de autenticação 3D Secure, conclusões assíncronas de Métodos Alternativos de Pagamento (APM) ou a receção de um estorno.
Dentro da pilha de pagamentos, os webhooks atuam como o tecido conectivo entre o adquirente ou PSP e o sistema interno de gestão de pedidos (OMS) ou plataforma de gestão de receitas do comerciante.
Eles garantem que a lógica subsequente, como o bloqueio de inventário ou o direito digital, permanece precisa sem introduzir latência ou sobrecarga de API desnecessária.
A implementação adequada exige um tratamento robusto de códigos de status HTTP e idempotência para gerir potenciais novas tentativas do servidor de envio, garantindo que cada evento é processado uma e apenas uma vez.
Como funciona Webhooksfunciona
Definir Endpoint e Eventos
Um comerciante especifica um URL de destino no seu ambiente para receber pedidos POST. Ele seleciona acionadores de eventos específicos do ciclo de vida do pagamento, como sucesso de autorização, início de reembolso ou criação de disputa. Isso garante que o seu sistema processa apenas pacotes de dados relevantes, reduzindo a carga desnecessária do servidor e mantendo os pontos de integração focados e gerenciáveis.
Acionador de Evento e Carga Útil
Quando ocorre uma alteração de estado, como um cliente a completar um desafio SCA, o sistema gera uma carga JSON. Esta carga contém dados estruturados, incluindo o ID da transação, o ID do comerciante (MID), o valor e o tipo de evento específico. A gateway tenta então entregar estes dados ao endpoint registado.
Segurança e Verificação de Assinatura
Para evitar a injeção não autorizada de dados, a carga é geralmente assinada com uma chave secreta. O servidor do comerciante reconstrói a assinatura usando o corpo do pedido bruto e compara-a com o cabeçalho. Esta verificação garante que os dados se originaram da fonte fidedigna e não foram adulterados durante o trânsito.
Porque é que Webhooks é importante
Eficiência Operacional e Automação
A dependência de verificações de status manuais ou sondagens periódicas da API introduz latência que pode degradar a experiência do utilizador e atrasar a execução. Os Webhooks automatizam a transição entre a autorização de pagamento e a entrega do serviço. Ao receber notificação imediata de capturas ou liquidações bem-sucedidas, as empresas podem automatizar fluxos de trabalho de envio, geração de licenças ou provisionamento de contas, reduzindo a necessidade de intervenção manual e minimizando o risco de erro humano na gestão de transações.
Mitigação de Riscos e Disputas
As notificações para pedidos de recuperação ou estornos permitem que os comerciantes respondam dentro dos prazos impostos pelo esquema. Alertas imediatos sobre recusas leves ou falhas de SCA permitem um envolvimento proativo do cliente. Ao reagir a esses eventos à medida que acontecem, os comerciantes podem melhorar as suas taxas de sucesso de representação e reduzir os custos operacionais associados a falhas de pagamento não abordadas ou disputas que, de outra forma, poderiam ter passado despercebidas até uma auditoria manual periódica.
Notas regulamentares para Webhooks
Data privacy and payload security
Transmitting transaction data across open networks leaves no slack against data protection regulations like GDPR and PCI DSS. Notification payloads must travel exclusively over TLS-encrypted connections to prevent interception by unauthorised third parties during transit.
Cardflo enforces HTTPS URLs for all registered listener endpoints, rejecting any unencrypted destinations.
Furthermore, structured notifications exclude sensitive cardholder data, such as full primary account numbers or security codes. The gateway transmits tokenised identifiers and masked references, ensuring that the receiving server does not inadvertently bring its hosting environment into the highest tiers of PCI DSS compliance scope.
PSD2 and asynchronous strong customer authentication
Under Payment Services Directive 2, Strong Customer Authentication introduces asynchronous flows into the standard checkout process. When a transaction requires an out-of-band authentication step, such as a biometric check in a banking application, the initial request cannot return an immediate definitive success or failure status.
Event listeners are essential for capturing the final outcome of these mandated security challenges. Once the issuing bank confirms the authentication result through the acquirer partner network, the orchestration layer fires an asynchronous event.
This notification informs the merchant system that the security requirement is satisfied and the capture can proceed.
Casos de uso de Webhookscasos de uso
Ciclo de Vida de Subscrição e SaaS
Quando um pagamento recorrente falha ou um cartão expira, um webhook aciona uma sequência de cobrança automatizada ou suspende o acesso do utilizador, mantendo ciclos de faturação precisos sem supervisão manual.
Cumprimento de Pedidos de Comércio Eletrónico
Um varejista online usa webhooks para liberar mercadorias para envio somente após receber um evento 'capture.succeeded', impedindo o despacho de itens para os quais o pagamento não foi totalmente autorizado.
Coordenação de Pagamentos em Marketplaces
As plataformas que recebem fundos podem acionar desembolsos para sub-comerciantes somente após a transação inicial do cliente atingir o status liquidado, garantindo liquidez e reduzindo o risco de reversões de pagamento.
Finalização de Método de Pagamento Alternativo
Para métodos como transferências bancárias ou esquemas locais que não fornecem confirmação instantânea, os webhooks notificam o sistema horas ou dias depois, quando os fundos são confirmados.
Webhooks em números
Atraso típico da indústria entre o registo de um evento na plataforma adquirente e o webhook ser enviado para o endpoint do comerciante.
Referência de confiabilidade padrão para serviços de webhook ao incluir lógica de nova tentativa automatizada e infraestrutura de entrega redundante.
Observação da indústria sobre a melhoria na velocidade de execução ao fazer a transição de processamento em lote periódico para arquiteturas de webhook baseadas em eventos.
Metodologia: estes valores são intervalos meramente indicativos, retirados de dados publicados do setor e de grupos de comerciantes observados, não constituindo garantias. Os resultados reais dependem do seu perfil de risco, da combinação de cartões, da geografia e da sua configuração de adquirência, sendo confirmados apenas nos seus próprios termos de preços e aprovação.
Termos relacionados
Fale com a nossa equipa sobre uma implementação live nas rails dos nossos parceiros adquirentes.
O que obtém com Webhooks
- Entrega assíncrona de alterações de estado de transação para um melhor desempenho do sistema.
- Suporte para múltiplos tipos de eventos, incluindo autorização, captura, reembolso e disputa.
- Cabeçalhos de assinatura HMAC-SHA256 para verificação robusta da integridade dos dados recebidos.
- Lógica de nova tentativa automatizada seguindo horários de espera exponencial para tentativas de entrega falhadas.
- Versão da carga para garantir a compatibilidade à medida que as estruturas de dados evoluem ao longo do tempo.
- Capacidades de whitelist de IP para restringir o tráfego de entrada a fontes de gateway conhecidas.
A short scoping call, then a written plan for your MIDs.
Perguntas sobre Webhooks
Como o nosso servidor deve lidar com notificações de webhook duplicadas?
É prática padrão para as gateways de pagamento empregarem um mecanismo de nova tentativa se um endpoint não retornar uma resposta 200 OK dentro de um prazo específico. Consequentemente, o seu servidor pode receber o mesmo evento várias vezes.
Para manter a integridade dos dados, deve implementar a lógica de idempotência. Isso normalmente envolve o rastreamento do ID de evento único fornecido na carga e a verificação se já foi processado antes de executar qualquer lógica de negócio.
Se o ID existir na sua base de dados, o seu servidor deve ignorar o evento, mas ainda retornar um 200 OK para parar novas tentativas.
Qual a diferença entre sondar uma API e usar webhooks?
A sondagem (polling) exige que o seu servidor inicie pedidos frequentes à gateway para verificar atualizações de estado, o que é ineficiente e pode levar a problemas de limitação de taxa ou informações atrasadas.
Os webhooks invertem este fluxo, onde a gateway inicia um pedido ao seu servidor apenas quando ocorre um evento.
Este modelo 'push' é mais eficiente, reduzindo a carga do servidor e garantindo que os estados são atualizados quase em tempo real em toda a sua infraestrutura, o que é particularmente importante para ações sensíveis ao tempo,
como entrega de conteúdo digital ou prevenção de fraude.
Por que a verificação de assinatura é necessária para cada solicitação de webhook?
Como os endpoints de webhook são URLs públicos, eles são teoricamente acessíveis por qualquer entidade na internet. Sem verificação, um atacante poderia enviar uma carga JSON falsa para o seu servidor, indicando falsamente que um pagamento de alto valor foi bem-sucedido.
Ao usar um segredo compartilhado para verificar a assinatura HMAC fornecida no cabeçalho do pedido, o seu sistema pode provar matematicamente que a mensagem foi enviada pelo seu PSP e que o conteúdo não foi alterado,
garantindo a segurança do seu processo de atendimento de pedidos.
Como os webhooks lidam com 3D Secure e os requisitos do SCA?
Durante um fluxo 3-DS, a transação muitas vezes entra em estado pendente enquanto o utilizador é redirecionado para o seu emissor para autenticação. O resultado final desta autenticação pode não ser conhecido imediatamente.
Os webhooks são usados para notificar o seu sistema quando o desafio 3-DS é concluído e a transação é subsequentemente autorizada ou recusada.
Isso impede que o seu checkout fique parado e permite que o seu backend reaja ao estado de autorização final assim que o cliente retorna da página de redirecionamento do banco.
Funcionalidades relacionadas.
Relacionados guias.
Veja como a Cardflo compara.
Preparado para melhorar a sua configuração de pagamentos?
Fale-nos do seu negócio. Iremos apresentá-lo aos parceiros adquirentes e à rota certa, normalmente em menos de uma semana.