Configuração

Criando um endpoint

Para receber notificações, crie um endpoint de webhook pelo painel ou via API:

curl -X POST https://api.payhubr.com/v1/postbacks/endpoints \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com/webhooks",
    "events": ["charge.captured", "charge.refunded", "charge.failed"]
  }'

A resposta inclui o secret do endpoint, que será exibido apenas uma vez:

{
  "data": {
    "id": "uuid-do-endpoint",
    "url": "https://meusite.com/webhooks",
    "secret": "a1b2c3d4e5f6...",
    "events": ["charge.captured", "charge.refunded", "charge.failed"],
    "status": "active",
    "created_at": "2026-02-24T10:00:00.000Z"
  }
}

Gerenciando endpoints

Cada endpoint pode ser atualizado individualmente:

• Alterar URL: PATCH /v1/postbacks/endpoints/{id} com { "url": "nova-url" }
• Alterar eventos: PATCH /v1/postbacks/endpoints/{id} com { "events": ["charge.captured"] }
• Pausar/ativar: PATCH /v1/postbacks/endpoints/{id} com { "status": "paused" } ou { "status": "active" }
• Remover: DELETE /v1/postbacks/endpoints/{id}

Segurança: assinatura HMAC-SHA256

Toda notificação inclui o header X-SoarLabz-Signature com uma assinatura HMAC-SHA256 do corpo da requisição. Use essa assinatura para verificar que a notificação realmente veio da PayHub.

Cada endpoint tem seu próprio secret, gerado automaticamente na criação. Você pode regenerar o secret a qualquer momento via POST /v1/postbacks/endpoints/{id}/secret/regenerate.

Validando a assinatura

Exemplos de validação

const crypto = require('crypto');

function validateSignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)