API de endpoints de webhook

Registe endpoints HTTPS para receber POSTs de eventos assinados com HMAC sempre que algo relevante acontece na plataforma — sessões abrem, provas são capturadas, cadeias de auditoria ancoram. Cada entrega é repetida com backoff exponencial, assinada com um segredo por endpoint e protegida contra replay através de uma janela de selo temporal de 5 minutos.

Para o catálogo de eventos + formatos de payload, consulte Visão geral dos webhooks. Esta página é a superfície de API para gerir endpoints + inspecionar tentativas de entrega.

O objeto Endpoint

{
  "id": "we-1f2a...",
  "url": "https://hooks.acme.com/cvp",
  "description": "Production claims pipeline",
  "event_types": ["session.completed", "evidence.created"],
  "active": true,
  "created_at": "2026-04-12T09:00:00Z"
}

Nota: o campo signing_secret é devolvido exatamente uma vez na resposta ao POST — guarde-o imediatamente, ou rode-o mais tarde via PATCH se o perder.

Listar endpoints

GET /api/v1/public/webhook-endpoints — âmbito webhooks:read

curl https://app.nexbasira.com/api/v1/public/webhook-endpoints \
  -H "Authorization: Bearer nb_sec_..."

Criar um endpoint

POST /api/v1/public/webhook-endpoints — âmbito webhooks:write

curl -X POST https://app.nexbasira.com/api/v1/public/webhook-endpoints \
  -H "Authorization: Bearer nb_sec_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.acme.com/cvp",
    "description": "Production claims pipeline",
    "event_types": ["session.completed", "evidence.created"]
  }'

Campos do corpo

{
  "id": "we-1f2a...",
  "url": "https://hooks.acme.com/cvp",
  "description": "Production claims pipeline",
  "event_types": ["session.completed", "evidence.created"],
  "active": true,
  "created_at": "2026-04-12T09:00:00Z",
  "signing_secret": "whsec_4f9d2a8b3c1e..."
}

O signing_secret é a chave HMAC-SHA256 que a plataforma usa para assinar cada POST. Verifique o cabeçalho NB-Signature no seu recetor — os nossos SDKs incluem um helper de uma linha.

Obter / atualizar / eliminar

GET / PATCH / DELETE /api/v1/public/webhook-endpoints/{endpoint_id}

GET requer webhooks:read; PATCH + DELETE requerem webhooks:write. PATCH aceita o mesmo formato de corpo que POST — todos os campos opcionais. Use-o para pausar um endpoint ({"active": false}), restringir a sua subscrição ou rodar o segredo de assinatura.

Rodar o segredo de assinatura

curl -X PATCH https://app.nexbasira.com/api/v1/public/webhook-endpoints/we-1f2a... \
  -H "Authorization: Bearer nb_sec_..." \
  -H "Content-Type: application/json" \
  -d '{"rotate_secret": true}'

O novo segredo é devolvido exatamente uma vez no corpo da resposta, com o mesmo formato da chamada de criação. Tanto o segredo antigo como o novo são válidos durante as próximas 24 h para dar tempo ao seu recetor de fazer o deploy — depois disso o antigo é revogado.

Inspecionar tentativas de entrega

GET /api/v1/public/webhook-events — âmbito webhooks:read

Últimas 100 tentativas de entrega da organização da credencial. Filtre por ?endpoint={id} ou ?status=pending|delivered|failed|dropped.

{
  "data": [{
    "id": "wev-9a01...",
    "endpoint": "we-1f2a...",
    "event_type": "session.completed",
    "status": "delivered",
    "response_status": 200,
    "attempt_count": 1,
    "created_at": "2026-05-23T10:32:00Z",
    "delivered_at": "2026-05-23T10:32:01Z"
  }],
  "has_more": false,
  "next_cursor": null
}

Cadência de repetição

As entregas falhadas são repetidas segundo este calendário e depois descartadas:

• +30 segundos
• +5 minutos
• +1 hora
• +6 horas
• +24 horas
• depois disso → dropped (visível no registo de entregas)

Erros comuns