Visão Geral
Entenda como o sistema de webhooks da SoarLabz funciona e como receber notificações em tempo real sobre eventos da sua conta.
O que são webhooks?
Webhooks são notificações HTTP enviadas automaticamente pela SoarLabz 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 SoarLabz envia um POST com os dados do evento assim que ele ocorre.
Como funciona
- Você cria um ou mais endpoints de webhook no painel, cada um com uma URL e os eventos que deseja receber
- Quando um evento ocorre, a SoarLabz envia um
HTTP POSTpara todos os endpoints ativos que estão inscritos nesse evento - Sua aplicação processa a notificação e responde com um status
2xx - Se a entrega falhar, a SoarLabz reenvia automaticamente com backoff exponencial
Múltiplos endpoints
Você pode configurar quantos endpoints quiser. Cada endpoint possui:
| Campo | Descrição |
|---|---|
| URL | A URL que receberá as notificações via HTTP POST |
| Eventos | Lista de eventos que este endpoint recebe (ex: charge.captured, charge.refunded) |
| Secret | Chave HMAC-SHA256 exclusiva para verificar a autenticidade das notificações |
| Status | active (recebe notificações) ou paused (temporariamente desativado) |
Cada endpoint tem seu próprio secret. Isso permite que você integre com múltiplos sistemas, cada um com sua própria chave de verificação.
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"
}| Campo | Tipo | Descrição |
|---|---|---|
id | string | Identificador único da entrega (delivery log) |
event | string | Nome do evento (ex: charge.captured, submerchant.approved, withdrawal.completed) |
charge | object | Dados da cobrança (presente em eventos charge.*) |
submerchant | object | Dados do submerchant (presente em eventos submerchant.*) |
withdrawal | object | Dados do saque (presente em eventos withdrawal.*) |
occurred_at | string | Data/hora em que o evento ocorreu (ISO 8601) |
Headers HTTP
Cada notificação inclui os seguintes headers:
| Header | Descrição |
|---|---|
Content-Type | application/json |
X-SoarLabz-Signature | Assinatura HMAC-SHA256 do payload (ex: sha256=abc123...) |
X-SoarLabz-Event | Nome do evento (ex: charge.captured) |
X-SoarLabz-Delivery-Id | ID único da entrega |
User-Agent | SoarLabz-Postback/1.0 |