Webhooks

Conceitos rápidos

A API publica eventos para URLs cadastradas e assina cada entrega com HMAC SHA-256.

Headers enviados ao destino:

• content-type: application/json
• x-webhook-signature
• x-webhook-event
• x-webhook-id

Formato da entrega

O corpo enviado para o destino do webhook segue este formato:

{
  "eventId": "uuid-ou-id-unico",
  "eventType": "transaction.updated",
  "occurredAt": "2026-03-26T12:00:00.000Z",
  "payload": {
    "transactionId": "uuid",
    "status": "Success"
  }
}

Event groups usados na API

Os grupos observados no código são:

• transaction
• vault
• balance

Criar um webhook

Endpoint: POST /webhooks

Serve para

Criar um webhook vinculado ao API user autenticado.

Autenticação

Exige bearer token com permissão webhook:write.

Body

{
  "eventGroup": "transaction",
  "targetUrl": "https://example.com/webhooks"
}

Retorno

Retorna o webhook criado.

Campos principais:

• id
• apiUserId
• eventGroup
• targetUrl
• secret
• status
• createdAt
• updatedAt

Listar webhooks do usuário atual

Endpoint: GET /webhooks

Serve para

Listar os webhooks do API user atual.

Autenticação

Exige bearer token com permissão webhook:read.

Retorno

Array de webhooks do usuário atual.

Listar entregas de um webhook

Endpoint: GET /webhooks/:webhookId/deliveries

Serve para

Listar o histórico de entregas de um webhook específico do usuário atual.

Autenticação

Exige bearer token com permissão webhook:read.

Parâmetros de rota

• webhookId UUID do webhook.

Query params

• status Filtra por status da entrega.
• eventType Filtra por tipo de evento.

Retorno

Array de entregas.

Campos principais por item:

• id
• webhookId
• eventId
• eventType
• payloadJson
• attemptCount
• status
• responseStatus
• responseBody
• lastAttemptAt
• createdAt

Consultar uma entrega específica

Endpoint: GET /webhooks/deliveries/:deliveryId

Serve para

Consultar uma entrega específica.

Autenticação

Exige bearer token com permissão webhook:read.

Retorno

Retorna a entrega completa, incluindo payloadJson e dados de resposta.

Reenviar manualmente uma entrega

Endpoint: POST /webhooks/deliveries/:deliveryId/replay

Serve para

Reenviar manualmente uma entrega de webhook.

Autenticação

Exige bearer token com permissão webhook:write.

Retorno

Retorna a entrega atualizada após a nova tentativa.

Observações

• A API faz até 3 tentativas por replay.
• O campo status da entrega pode ficar como pending, retrying, delivered ou failed.

Criar um webhook global como admin

Endpoint: POST /admin/webhooks

Serve para

Criar um webhook global, sem vínculo com um API user.

Autenticação

Exige token de admin.

Body

Mesmo formato do endpoint de criação comum.

Listar todos os webhooks como admin

Endpoint: GET /admin/webhooks

Serve para

Listar todos os webhooks cadastrados.

Autenticação

Exige token de admin.

Excluir um webhook como admin

Endpoint: DELETE /admin/webhooks/:id

Serve para

Excluir um webhook e suas entregas registradas.

Autenticação

Exige token de admin.

Parâmetros de rota

• id UUID do webhook.