API de endpoints de webhook

Registre endpoints HTTPS para recibir POST de eventos firmados con HMAC cada vez que ocurre algo interesante en la plataforma — se abren sesiones, se capturan pruebas, se anclan cadenas de auditoría. Cada entrega se reintenta con retroceso exponencial, se firma con un secreto por endpoint y es segura ante reenvíos mediante una ventana de sello de tiempo de 5 minutos.

Para el catálogo de eventos y las formas de payload, consulte Visión general de webhooks. Esta página es la superficie de la API para gestionar endpoints e inspeccionar intentos de entrega.

El 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: el campo signing_secret se devuelve exactamente una vez en la respuesta POST — guárdelo de inmediato, o rótelo más tarde mediante PATCH si lo pierde.

Listar endpoints

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

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

Crear un endpoint

POST /api/v1/public/webhook-endpoints — alcance 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 del cuerpo

{
  "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..."
}

El signing_secret es la clave HMAC-SHA256 que la plataforma usa para firmar cada POST. Verifique la cabecera NB-Signature en su receptor — nuestros SDK incluyen un ayudante de una línea.

Recuperar / actualizar / eliminar

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

GET necesita webhooks:read; PATCH + DELETE necesitan webhooks:write. PATCH acepta la misma forma de cuerpo que POST — todos los campos opcionales. Úselo para pausar un endpoint ({"active": false}), reducir su suscripción o rotar el secreto de firma.

Rotar el secreto de firma

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}'

El nuevo secreto se devuelve exactamente una vez en el cuerpo de la respuesta, con la misma forma que la llamada de creación. Tanto el secreto antiguo como el nuevo son válidos durante las próximas 24 h para dar tiempo a que su receptor lo despliegue — después de eso, el antiguo se revoca.

Inspeccionar intentos de entrega

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

Últimos 100 intentos de entrega para la organización de la credencial. Filtre por ?endpoint={id} o ?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
}

Cadencia de reintentos

Las entregas fallidas se reintentan según este calendario y luego se descartan:

• +30 segundos
• +5 minutos
• +1 hora
• +6 horas
• +24 horas
• después de eso → dropped (visible en el registro de entrega)

Errores comunes