Criar webhook

Cria um novo endpoint de webhook global. Retorna o `secret` em **plain-text uma única vez** — guarde-o pra validar assinatura HMAC dos POSTs futuros. Você nunca conseguirá ver esse secret de novo (só rotacionar). A `url` precisa ser HTTPS em produção. A array `events` aceita os 12 eventos suportados (veja [Eventos disponíveis (V2)](/docs/webhook-configuration)).

POST/v2/webhooks

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

urlstring (body)obrigatório

URL pública que receberá os POSTs. HTTPS exigido em produção.

Exemplo: https://api.seu-dominio.com/webhooks/exstack

descriptionstring (body)opcional

Label opcional pra você identificar (ex: 'Slack alerts', 'ERP').

Exemplo: Webhook ERP

eventsstring[] (body)obrigatório

Lista de eventos pra subscribe. Pelo menos 1. Veja a lista completa em /docs/webhook-configuration.

Exemplo: ["cashin.paid", "cashin.refunded"]

Respostas

201

Webhook criado. secret retornado uma única vez aqui.

JSON

{
  "id": "wh_8f2c1a9d",
  "url": "https://api.seu-dominio.com/webhooks/exstack",
  "description": "Webhook ERP",
  "events": ["cashin.paid", "cashin.refunded"],
  "active": true,
  "environment": "LIVE",
  "secret": "whsec_abc123XYZ...",
  "createdAt": "2026-05-28T15:30:00.000Z"
}

400

URL inválida ou evento desconhecido.

JSON

{ "status": 400, "error": "evento desconhecido: foo.bar" }

Exemplos

cURL

curl -X POST "https://api.pagnovo.com/v2/webhooks" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.seu-dominio.com/webhooks/exstack",
    "description": "Webhook ERP",
    "events": ["cashin.paid", "cashin.refunded"]
  }'