Visão geral

Introdução

O recurso de Webhook Events é o histórico de todas as notificações geradas para os Webhook Endpoints configurados. Ele permite monitorar a entrega de eventos, verificar o status, identificar falhas e reenviar (replay) eventos quando necessário, garantindo que os sistemas integrados permaneçam sincronizados com a plataforma.

Conceito e Funcionalidade

Cada evento registra uma ocorrência na sua conta (ex.: transaction.approved), seu tipo, o recurso afetado e o resultado da entrega. A partir do evento, a plataforma cria um ou mais dispatches — uma tentativa de entrega por endpoint elegível. A listagem de eventos já traz os dispatches aninhados em cada item.

Timeout e Retentativas

A plataforma aguarda a resposta do seu endpoint por até 30 segundos. Sem resposta 2xx nesse período (ou em caso de erro/timeout), a tentativa é registrada como falha e o sistema agenda uma nova tentativa com backoff (até esgotar as retentativas, ~3 dias).

Fluxo de Entrega de Eventos

Eventos podem ser reenviados manualmente via POST /v1/webhooks/events/{eventId}/resend (veja Reenviar Evento). Valide sempre a assinatura X-Selectwin-Signature antes de processar o payload.

Estrutura do Objeto Evento (respostas da API)

Itens de listagem de events (com dispatches aninhados; envelope paginado com merchant/_links no root):

{
  "id": "wbh_01hqzvabc",
  "type": "transaction.approved",
  "resource": "transaction",
  "resourceId": "tra_987654321",
  "source": "automatic",
  "delivered": true,
  "attempts": 1,
  "data": { "id": "tra_987654321", "status": "approved", "amount": 1500 },
  "createdAt": "2026-06-20T17:56:32.000Z",
  "dispatches": [ { "id": "wdi_01hqzvabc", "status": "success", "...": "..." } ]
}

Atributo	Tipo	Descrição
`id`	string	ID do evento (`wbh_*`)
`type`	string	Tipo do evento (ver Catálogo)
`resource`	string	Recurso afetado (ex.: `transaction`)
`resourceId`	string \| null	ID público do recurso
`source`	string	Origem do evento (`automatic`, `api`)
`delivered`	boolean	Se a entrega foi concluída com sucesso
`attempts`	integer	Total de tentativas de entrega
`data`	objeto	O objeto do recurso (mesma forma da leitura do recurso)
`createdAt`	string (ISO)	Data de criação do evento
`dispatches`	array	Tentativas de entrega aninhadas (ver Dispatches)
`merchant` / `_links`	object	Presentes na leitura individual e no envelope da lista

O reenvio (/resend) responde 202 Accepted com { "accepted": true, "id": "wbh_..." }.

Recursos Disponíveis

Recurso	Método	Caminho	Descrição
Listar Eventos	GET	`/v1/webhooks/events`	Lista eventos com paginação e filtros (dispatches aninhados)
Recuperar Evento	GET	`/v1/webhooks/events/{eventId}`	Recupera um evento e seus dispatches
Reenviar Evento	POST	`/v1/webhooks/events/{eventId}/resend`	Reentrega o evento a todos os endpoints elegíveis

🔒 Antes de processar qualquer evento em produção, verifique a assinatura HMAC. Veja Verificando Assinaturas de Webhook para o passo a passo e exemplos de código.

Tipos de Eventos

A lista completa e autoritativa está no Catálogo de Eventos de Webhook. Alguns dos principais tipos:

Categoria	Tipo de Evento	Descrição
Transações	`transaction.created`	Quando uma nova transação é criada
Transações	`transaction.approved`	Quando uma transação é aprovada
Transações	`transaction.failed`	Quando uma tentativa de transação falha
Transações	`transaction.canceled`	Quando uma transação é cancelada
Transações	`transaction.refunded`	Quando uma transação é estornada
Clientes	`customer.created`	Quando um novo cliente é criado
Clientes	`customer.updated`	Quando um cliente é atualizado
Clientes	`customer.deleted`	Quando um cliente é excluído
Endereços	`customer.address.created`	Quando um endereço de cliente é criado
Cartões	`card.created`	Quando um novo cartão é registrado
Cartões	`card.deleted`	Quando um cartão é removido
Carteiras	`wallet.created`	Quando uma nova carteira é criada
Carteiras	`wallet.enabled`	Quando uma carteira é ativada
Recebíveis	`receivable.paid`	Quando um recebível é pago/liberado
Webhooks	`webhook.created`	Quando um novo webhook endpoint é configurado

Casos de Uso Comuns

Monitoramento de Integrações: acompanhamento da saúde das integrações via webhook
Recuperação de Eventos: identificação e reenvio de eventos não entregues
Auditoria: histórico completo das notificações geradas
Depuração: análise de falhas de entrega via Dispatches

Melhores Práticas

Monitoramento Regular: verifique o status de entrega dos eventos.
Reenvio Seletivo: use o reenvio apenas para eventos que não foram entregues com sucesso.
Filtragem: ao listar, use os filtros (type, status, resource, endpoint, datas).
Deduplicação: processe cada id de evento (wbh_...) apenas uma vez.
Filas: processe os eventos de forma assíncrona e resiliente.

Integração com Outros Recursos

Webhook Endpoints: os eventos são entregues aos endpoints configurados.
Webhook Dispatches: cada tentativa de entrega é um dispatch auditável.
Transactions / Customers / Cards / Wallets / Finance / Checkout: geram eventos em mudanças de estado (ver Catálogo).

Visão geral

On this page