Como funcionam os Webhooks

Os Webhooks fornecem notificações de eventos em tempo real sobre suas transações e atividades de pagamento. Quando ocorrem eventos nos quais você se inscreveu, a Getnet envia uma solicitação HTTP POST para o endpoint do seu Webhook com os detalhes do evento.

Essa abordagem orientada a eventos permite que você receba atualizações imediatas sobre:

• Mudanças de status da transação (aprovada, rejeitada, capturada, cancelada, reembolsada)
• Eventos de pagamento (bem-sucedidos, falhos, pendentes)
• Atualizações de cartão (mudanças de validade, renovações de token)
• E outros eventos relacionados a pagamentos

Como funciona

Uma visão geral do fluxo de assinatura e notificação de webhooks pode ser vista no diagrama abaixo:

O sistema de Webhook segue um fluxo de trabalho de três etapas:

1. Configuração

Configure sua URL de Webhook e escolha quais eventos você deseja receber. Usando a Getnet Webhook Management API, você pode:

• Registrar uma URL de notificação
• Inscrever-se em tipos de eventos específicos com base nas necessidades do seu negócio
• Configurar a autenticação para o seu endpoint
• Atualizar ou remover assinaturas de Webhook existentes

Métodos de autenticação suportados

Ao registrar um Webhook, você deve escolher um dos três métodos de autenticação suportados:

1. Basic Auth (user_credentials) – A Getnet inclui um cabeçalho Authorization: Basic padrão composto pelo client_id e client_secret que você fornece. Configure seu endpoint para validar essas credenciais em cada chamada de Webhook.

2. OAuth 2.0 (oauth) – Antes de enviar o Webhook, a Getnet solicita um access token do servidor OAuth que você definir (usando o client ID e o secret fornecidos). O token resultante é então anexado à solicitação do Webhook como um Bearer token. Use esta opção quando o seu endpoint esperar Bearer tokens OAuth em vez de credenciais Basic.

3. Token (token) – A Getnet usa um Bearer token obtido da Getnet Authentication API. Este é o mesmo token que você usa para autenticar outras solicitações da API da Getnet. Use esta opção quando seu endpoint esperar Bearer tokens e você quiser usar o sistema de autenticação da Getnet. Consulte a documentação de Authentication para obter detalhes sobre como obter tokens do endpoint de autenticação.

Escolha a opção que corresponde à forma como o endpoint do seu Webhook autentica as chamadas recebidas. O modo oauth executa o fluxo completo de client credentials do OAuth 2.0 em seu nome, enquanto o token usa um token que você já obteve do endpoint de autenticação da Getnet.

Para configuração detalhada de autenticação, consulte a documentação Webhooks Reference.

Requisitos do endpoint

O endpoint do seu Webhook deve atender a estes requisitos:

• Aceitar solicitações HTTP POST
• Usar HTTPS com um certificado SSL válido
• Responder com o código de status HTTP 204 (No Content) quando o Webhook for recebido com sucesso

O endpoint do seu Webhook deve usar HTTPS com um certificado SSL válido. Acompanhe as datas de expiração dos certificados, pois certificados expirados impedirão a entrega do Webhook.

2. Notificação

Quando ocorre um evento no qual você está inscrito, a API da Getnet envia automaticamente uma solicitação HTTP POST para sua URL configurada, contendo todos os dados relevantes do evento. Isso acontece em tempo real à medida que as transações são processadas.

Tipos de eventos disponíveis

A Getnet oferece os seguintes tipos de eventos de Webhook que cobrem o ciclo de vida completo da transação:

Ao criar uma assinatura de Webhook, você especifica quais eventos deseja receber. Isso permite que você configure diferentes endpoints de Webhook para diferentes tipos de eventos ou lide com todos os eventos em um único endpoint.

Para detalhes completos sobre cada tipo de evento e seus payloads, consulte a documentação Webhook Payloads.

3. Recepção

Seu sistema de recepção processa a notificação e executa as ações apropriadas com base nas informações recebidas. Isso pode incluir:

• Atualizar o status do pedido no seu banco de dados
• Acionar notificações para clientes
• Iniciar processos de fulfillment (atendimento do pedido)
• Registrar os resultados das transações para conciliação
• Atualizar os tokens de cartão quando os detalhes do cartão mudam

Seu sistema deve confirmar o recebimento respondendo com um código de status 204 (No Content). Os eventos são processados e enviados apenas na conclusão bem-sucedida para garantir a integridade dos dados.

Webhook Management API

A Webhook Management API da Getnet fornece endpoints para gerenciar suas assinaturas de Webhook de forma programática. A API permite que você:

• Criar assinaturas – Registrar novos endpoints de Webhook para eventos específicos
• Listar assinaturas – Recuperar todas as suas assinaturas de Webhook
• Excluir assinaturas – Remover assinaturas de Webhook que você não precisa mais
• Ver o histórico de eventos – Listar todas as mensagens de Webhook enviadas para uma assinatura
• Reenviar eventos – Solicitar nova tentativa de entregas específicas de Webhook
• Listar eventos inscritos – Visualizar todos os eventos nos quais você está atualmente inscrito

Para a documentação detalhada dos endpoints da API, incluindo schemas de request/response, parâmetros e exemplos, consulte a documentação de API Reference e Webhooks Reference.

Você pode configurar URLs de Webhook diferentes para ambientes diferentes (desenvolvimento, homologação, produção) ou para tipos de eventos diferentes, a fim de organizar melhor a sua integração.

Confiabilidade e lógica de retentativa

Se o endpoint do seu Webhook falhar em responder com sucesso (código de status diferente de 204, timeout ou erro de rede), a Getnet repetirá automaticamente a entrega do Webhook para garantir uma notificação de evento confiável.

Payloads do Webhook

Cada evento de Webhook inclui um payload JSON com os detalhes da transação. A estrutura do payload varia de acordo com o tipo de evento e o método de pagamento. Todos os payloads incluem:

• Identificadores da transação (payment_id, order_id, transaction_id)
• Informações de valor e moeda
• Códigos de status e motivo (reason codes)
• Timestamps no formato ISO 8601
• Campos específicos do evento

Para a documentação completa dos payloads, incluindo descrições de campos, exemplos para cada tipo de evento e campos específicos do método de pagamento, consulte a documentação Webhook Payloads.

Próximos passos

Agora que você entende como os Webhooks funcionam, você está pronto para integrá-los à sua aplicação:

1. Revisar as opções de autenticação – Escolha o método de autenticação que atenda aos requisitos do seu endpoint. Consulte Webhooks Reference para obter detalhes.

2. Explorar os eventos disponíveis – Revise os tipos de eventos e determine de quais você precisa. Consulte Webhooks Reference para obter a lista completa.

3. Configurar o seu endpoint – Certifique-se de que o endpoint do seu Webhook atenda aos requisitos e possa lidar com os payloads esperados.

4. Criar assinaturas – Use a Webhook Management API para criar assinaturas. Consulte a API Reference para obter detalhes do endpoint.

5. Revisar as estruturas de payload – Familiarize-se com a estrutura do payload para cada tipo de evento que você receberá. Consulte a documentação Webhook Payloads para obter detalhes completos.