Webhooks

Autenticação: X-API-Key (ou token de aluno). Conceito e validação de assinatura no guia de Webhooks.

Registrar

POST/v1/webhooks🔒 X-API-Key

curl

curl -X POST "$BASE/webhooks" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://seu-app.exemplo.com/webhooks","events":["order.paid"]}'

201

{ "id": "wh_...", "url": "https://seu-app.exemplo.com/webhooks",
  "events": ["order.paid"], "signingSecret": "whsec_...guarde-agora" }

signingSecret

Mostrado uma vez. É com ele que você valida o header X-Signature.

Listar, remover e eventos

GET/v1/webhooks🔒 X-API-Key

DELETE/v1/webhooks/:id🔒 X-API-Key

GET/v1/webhooks/events🔒 X-API-Key

Testar e auditar entregas

POST/v1/webhooks/:id/ping🔒 X-API-Key

GET/v1/webhooks/deliveries🔒 X-API-Key

Fluxo de teste sem app público

1. POST /webhooks com uma URL de teste (ex.: webhook.site).
2. POST /webhooks/:id/ping para disparar um evento.
3. GET /webhooks/deliveries para ver status HTTP e corpo de cada tentativa.

Payload recebido

{ "id": "evt_...", "type": "order.paid", "createdAt": "2026-08-05T12:00:00Z",
  "data": { "orderId": "cmse...", "total": 359.7 } }

Headers: X-Webhook-Event, X-Timestamp, X-Signature: sha256=<hmac>. Lembre da idempotência (entrega at-least-once): use o id para não processar duas vezes.