Webhooks
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.
- Categoria
- Programador
- Funcionalidades
- 10
- Disponível em
- Todos os planos
A visão geral
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 3-D 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
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.
Reconhecer e Processar
O servidor do comerciante deve retornar um código de status 200 OK prontamente para confirmar o recebimento. A lógica interna então é executada, como a atualização de um registro de banco de dados ou o acionamento de um e-mail automatizado.
Se o servidor estiver offline ou retornar um erro, o sistema de entrega segue um agendamento de nova tentativa programado para garantir a consistência dos dados.
Por que importa
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.
Casos 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.
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.
Termos relacionados
Talk to our team about a live rollout on your acquiring stack.
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.
- Inclusão de chave de idempotência para evitar o processamento duplicado do mesmo evento de pagamento.
- Registos de eventos detalhados para depuração e auditoria do desempenho da entrega de webhook dentro do dashboard.
- Seleção granular de eventos para minimizar o uso de largura de banda e os requisitos de processamento do lado do servidor.
- Funcionalidade de modo de teste para validar o comportamento do endpoint com cenários de pagamento simulados.
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 3-D 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.
Os webhooks podem ser usados para gerir os prazos de estorno e disputa?
Sim, os webhooks são uma ferramenta principal para gerir o ciclo de vida da disputa. Quando um titular de cartão inicia um Pedido de Recuperação ou um Estorno formal com o seu emissor, a gateway recebe esta notificação através dos esquemas de cartão.
Um webhook é então enviado para o seu sistema especificando o código do motivo, valor e prazo para resposta.
Usando estes dados em tempo real, pode automatizar a suspensão da conta relevante e notificar a sua equipa de risco para iniciar o processo de representação imediatamente, aumentando a probabilidade de uma anulação bem-sucedida da disputa.
O que acontece se o nosso servidor estiver inativo durante um evento de webhook crítico?
Sistemas de webhook confiáveis operam com uma política de novas tentativas. Se o seu endpoint retornar um erro 4xx ou 5xx, ou falhar em responder em poucos segundos, a gateway colocará a mensagem em fila para reentrega.
Essas novas tentativas geralmente seguem um padrão de espera exponencial, tentando a entrega várias vezes ao longo de minutos ou horas.
Para garantir consistência a longo prazo, também deve ter um mecanismo de fallback, como um script de reconciliação diária que chama a API para encontrar quaisquer alterações de status perdidas, fornecendo uma rede de segurança para interrupções prolongadas.
Funcionalidades relacionadas.
Pronto para a velocidade?
Fale-nos do seu negócio. Iremos apresentá-lo aos parceiros adquirentes e à rota certa, normalmente em menos de uma semana.