Visão Geral

O que são webhooks?

Webhooks são notificações HTTP enviadas automaticamente pela PayHub para a sua aplicação quando eventos importantes acontecem, como a captura de uma cobrança, um estorno ou um chargeback.

Em vez de consultar a API periodicamente para verificar mudanças (polling), você configura endpoints de webhook e a PayHub envia um POST com os dados do evento assim que ele ocorre.

Como funciona

1. Você cria um ou mais endpoints de webhook no painel, cada um com uma URL e os eventos que deseja receber
2. Quando um evento ocorre, a PayHub envia um HTTP POST para todos os endpoints ativos que estão inscritos nesse evento
3. Sua aplicação processa a notificação e responde com um status 2xx
4. Se a entrega falhar, a PayHub reenvia automaticamente com backoff exponencial

Múltiplos endpoints

Você pode configurar quantos endpoints quiser. Cada endpoint possui:

Estrutura do payload

Todos os webhooks seguem a mesma estrutura de envelope, com o campo de dados variando conforme o tipo de evento:

{
  "id": "uuid-do-delivery-log",
  "event": "charge.captured",
  "charge": { "..." },
  "occurred_at": "2026-02-24T10:00:00.000Z"
}

{
  "id": "uuid-do-delivery-log",
  "event": "submerchant.approved",
  "submerchant": { "..." },
  "occurred_at": "2026-03-30T14:00:00.000Z"
}

{
  "id": "uuid-do-delivery-log",
  "event": "withdrawal.completed",
  "withdrawal": { "..." },
  "occurred_at": "2026-03-30T14:05:00.000Z"
}

Headers HTTP

Cada notificação inclui os seguintes headers:

Eventos disponíveis