Webhooks (API) — Endpoints de la API de Belfort

Listar endpoints

GET /v1/developer/webhooks

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:read.

Tus endpoints de webhook registrados.

Parámetros

`limit` query	Tamaño de página (1–100).
`startingAfter` query	`nextCursor` de la página anterior. Excluyente con `endingBefore`.
`endingBefore` query	`previousCursor` de la página actual. Excluyente con `startingAfter`.
`includeTotal` query	Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.
`applicationId` query

Respuestas

200 Successful Response — ListEnvelope_WebhookEndpointResponse_

Campo	Requerido	Tipo	Descripción
`data`	sí	`WebhookEndpointResponse[]`
`hasMore`	sí	`boolean`	`true` si quedan resultados después de esta página.
`limit`	sí	`integer`	El límite realmente aplicado (puede ser menor al pedido).
`nextCursor`	no	`string \| null`	Pásalo como `startingAfter` para la siguiente página.
`object`	no	`"list"`
`previousCursor`	no	`string \| null`	Pásalo como `endingBefore` para la página anterior.
`totalCount`	no	`integer \| null`	Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.

Errores posibles (problem+json): 400 405 422 500

Registrar un endpoint

POST /v1/developer/webhooks

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:write.

Da de alta una URL y los eventos a los que se suscribe. La respuesta trae el signing secret en claro, una sola vez: guárdalo ahora, no se puede volver a consultar.

Cuerpo de la petición

application/json · schema WebhookEndpointCreate

Campo	Requerido	Tipo	Descripción
`applicationId`	no	`string \| null`	Opaque application id.
`description`	no	`string \| null`
`environment`	no	`live \| test`
`events`	no	`string[]`
`url`	sí	`string (uri)`

Respuestas

201 Successful Response — WebhookEndpointCreated

Campo	Requerido	Tipo	Descripción
`applicationId`	sí	`string \| null`	Opaque application id.
`createdAt`	sí	`string (date-time)`
`description`	sí	`string \| null`
`environment`	sí	`live \| test`
`events`	sí	`array \| null`
`id`	sí	`string`	Opaque webhook endpoint id.
`isActive`	sí	`boolean`
`secret`	sí	`string`
`updatedAt`	sí	`string (date-time)`
`url`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Consultar un endpoint

GET /v1/developer/webhooks/{endpoint_id}

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:read.

Configuración del endpoint. Nunca incluye el secreto.

Parámetros

endpoint_id path · requerido string

Respuestas

200 Successful Response — WebhookEndpointResponse

Campo	Requerido	Tipo	Descripción
`applicationId`	sí	`string \| null`	Opaque application id.
`createdAt`	sí	`string (date-time)`
`description`	sí	`string \| null`
`environment`	sí	`live \| test`
`events`	sí	`array \| null`
`id`	sí	`string`	Opaque webhook endpoint id.
`isActive`	sí	`boolean`
`updatedAt`	sí	`string (date-time)`
`url`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Editar un endpoint

PATCH /v1/developer/webhooks/{endpoint_id}

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:write.

Cambia URL, eventos, descripción o si está activo. Desactivarlo es la forma de dejar de recibir sin perder el historial: por eso no hay borrado.

Parámetros

endpoint_id path · requerido string

Cuerpo de la petición

application/json · schema WebhookEndpointUpdate

Campo	Requerido	Tipo	Descripción
`applicationId`	no	`string \| null`	Opaque application id.
`description`	no	`string \| null`
`events`	no	`string[] \| null`
`isActive`	no	`boolean \| null`
`url`	no	`string (uri) \| null`

Respuestas

200 Successful Response — WebhookEndpointResponse

Campo	Requerido	Tipo	Descripción
`applicationId`	sí	`string \| null`	Opaque application id.
`createdAt`	sí	`string (date-time)`
`description`	sí	`string \| null`
`environment`	sí	`live \| test`
`events`	sí	`array \| null`
`id`	sí	`string`	Opaque webhook endpoint id.
`isActive`	sí	`boolean`
`updatedAt`	sí	`string (date-time)`
`url`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Rotar el signing secret

POST /v1/developer/webhooks/{endpoint_id}/rotate-secret

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:write.

Genera un secreto nuevo, que se muestra una sola vez. Durante 24 horas cada entrega va firmada con el nuevo y con el anterior, así que puedes desplegar tu cambio sin perder eventos.

Parámetros

`endpoint_id` path · requerido	string
`Idempotency-Key` header

Respuestas

200 Successful Response — WebhookEndpointCreated

Campo	Requerido	Tipo	Descripción
`applicationId`	sí	`string \| null`	Opaque application id.
`createdAt`	sí	`string (date-time)`
`description`	sí	`string \| null`
`environment`	sí	`live \| test`
`events`	sí	`array \| null`
`id`	sí	`string`	Opaque webhook endpoint id.
`isActive`	sí	`boolean`
`secret`	sí	`string`
`updatedAt`	sí	`string (date-time)`
`url`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Enviar un evento de prueba

POST /v1/developer/webhooks/{endpoint_id}/test

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:write.

Manda un evento firmado a tu endpoint y te dice qué respondió. Síncrono y fuera de la cola: sirve para comprobar tu verificador en el momento.

Parámetros

endpoint_id path · requerido string

Cuerpo de la petición

application/json

Campo	Requerido	Tipo	Descripción
`eventType`	no	`string \| null`

Respuestas

200 Successful Response — WebhookTestResult

Campo	Requerido	Tipo
`delivered`	sí	`boolean`
`error`	sí	`string \| null`
`sentPayload`	sí	`object`
`statusCode`	sí	`integer \| null`

Errores posibles (problem+json): 400 405 422 500

Comprobar una firma

POST /v1/developer/webhooks/{endpoint_id}/verify-signature

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:read.

Le pasas un cuerpo tal cual lo recibiste y recomputa la firma esperada. Es la herramienta para depurar un verificador que rechaza entregas legítimas, normalmente porque algo en tu servidor reescribió el cuerpo antes de que lo vieras.

Parámetros

endpoint_id path · requerido string

Cuerpo de la petición

application/json · schema WebhookSignatureVerifyRequest

Campo	Requerido	Tipo
`messageId`	sí	`string`
`payload`	sí	`string`
`signature`	sí	`string`
`timestamp`	sí	`integer`

Respuestas

200 Successful Response — WebhookSignatureVerifyResult

Campo	Requerido	Tipo	Descripción
`expectedSignature`	sí	`string`
`valid`	sí	`boolean`

Errores posibles (problem+json): 400 405 422 500

Catálogo de eventos

GET /v1/developer/webhooks/event-types

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:read.

Los tipos de evento que Belfort emite y los patrones válidos para suscribirse.

Respuestas

200 Successful Response — WebhookEventTypeCatalog

Campo	Requerido	Tipo	Descripción
`eventTypes`	sí	`WebhookEventTypeItem[]`
`patterns`	sí	`string[]`

Errores posibles (problem+json): 400 405 422 500

Política de entrega

GET /v1/developer/webhooks/delivery-policy

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:read.

Cuántas veces se reintenta, con qué espera, qué se considera fallo permanente y qué tiempo máximo de respuesta se espera de ti.

Respuestas

200 Successful Response — WebhookDeliveryPolicy

Campo	Requerido	Tipo
`backoffBaseSeconds`	sí	`integer`
`httpTimeoutSeconds`	sí	`integer`
`maxBackoffSeconds`	sí	`integer`
`permanentVsTransientRule`	sí	`string`
`rateLimitDefaultRpm`	sí	`integer`
`recommendedToleranceSeconds`	sí	`integer`
`retryBudgetNote`	sí	`string`
`signatureScheme`	sí	`string`

Errores posibles (problem+json): 400 405 422 500

Listar entregas

GET /v1/developer/webhooks/deliveries

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:read.

Todas las entregas de todos tus endpoints.

Parámetros

`limit` query	Tamaño de página (1–100).
`startingAfter` query	`nextCursor` de la página anterior. Excluyente con `endingBefore`.
`endingBefore` query	`previousCursor` de la página actual. Excluyente con `startingAfter`.
`includeTotal` query	Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.
`applicationId` query

Respuestas

200 Successful Response — ListEnvelope_WebhookDeliveryResponse_

Campo	Requerido	Tipo	Descripción
`data`	sí	`WebhookDeliveryResponse[]`
`hasMore`	sí	`boolean`	`true` si quedan resultados después de esta página.
`limit`	sí	`integer`	El límite realmente aplicado (puede ser menor al pedido).
`nextCursor`	no	`string \| null`	Pásalo como `startingAfter` para la siguiente página.
`object`	no	`"list"`
`previousCursor`	no	`string \| null`	Pásalo como `endingBefore` para la página anterior.
`totalCount`	no	`integer \| null`	Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.

Errores posibles (problem+json): 400 405 422 500

Entregas de un endpoint

GET /v1/developer/webhooks/{endpoint_id}/deliveries

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:read.

Lo mismo, acotado a un endpoint.

Parámetros

`endpoint_id` path · requerido	string
`limit` query	Tamaño de página (1–100).
`startingAfter` query	`nextCursor` de la página anterior. Excluyente con `endingBefore`.
`endingBefore` query	`previousCursor` de la página actual. Excluyente con `startingAfter`.
`includeTotal` query	Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.

Respuestas

200 Successful Response — ListEnvelope_WebhookDeliveryResponse_

Campo	Requerido	Tipo	Descripción
`data`	sí	`WebhookDeliveryResponse[]`
`hasMore`	sí	`boolean`	`true` si quedan resultados después de esta página.
`limit`	sí	`integer`	El límite realmente aplicado (puede ser menor al pedido).
`nextCursor`	no	`string \| null`	Pásalo como `startingAfter` para la siguiente página.
`object`	no	`"list"`
`previousCursor`	no	`string \| null`	Pásalo como `endingBefore` para la página anterior.
`totalCount`	no	`integer \| null`	Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.

Errores posibles (problem+json): 400 405 422 500

Intentos de una entrega

GET /v1/developer/webhooks/deliveries/{delivery_id}/attempts

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:read.

Cada intento con su código de respuesta y su latencia. Es por donde se diagnostica un endpoint que falla de forma intermitente.

Parámetros

`delivery_id` path · requerido	string
`limit` query	Tamaño de página (1–100).
`startingAfter` query	`nextCursor` de la página anterior. Excluyente con `endingBefore`.
`endingBefore` query	`previousCursor` de la página actual. Excluyente con `startingAfter`.
`includeTotal` query	Calcula `totalCount`. Cuesta un `COUNT(*)` sobre el filtro entero, así que está apagado por defecto: pídelo solo cuando vayas a enseñar el total.

Respuestas

200 Successful Response — ListEnvelope_WebhookDeliveryAttemptResponse_

Campo	Requerido	Tipo	Descripción
`data`	sí	`WebhookDeliveryAttemptResponse[]`
`hasMore`	sí	`boolean`	`true` si quedan resultados después de esta página.
`limit`	sí	`integer`	El límite realmente aplicado (puede ser menor al pedido).
`nextCursor`	no	`string \| null`	Pásalo como `startingAfter` para la siguiente página.
`object`	no	`"list"`
`previousCursor`	no	`string \| null`	Pásalo como `endingBefore` para la página anterior.
`totalCount`	no	`integer \| null`	Total de coincidencias. Solo se calcula si pides `includeTotal=true` — es un `COUNT(*)` sobre el filtro entero y no se cobra a quien no lo necesita.

Errores posibles (problem+json): 400 405 422 500

Reintentar una entrega

POST /v1/developer/webhooks/deliveries/{delivery_id}/retry

Requiere una API key secreta (belfort_{env}_sk_…) con scope webhook:write.

Crea una entrega NUEVA del mismo evento, con la URL y el secreto actuales. El intento original se conserva en el historial.

Parámetros

delivery_id path · requerido string

Respuestas

200 Successful Response — WebhookDeliveryResponse

Campo	Requerido	Tipo	Descripción
`attempts`	sí	`integer`
`createdAt`	sí	`string (date-time)`
`endpointId`	sí	`string \| null`	Opaque webhook endpoint id.
`eventId`	sí	`string \| null`	Opaque event id.
`eventType`	sí	`string \| null`
`id`	sí	`string`	Opaque webhook delivery id.
`lastError`	sí	`string \| null`
`lastStatusCode`	sí	`integer \| null`
`nextRetryAt`	sí	`string (date-time) \| null`
`sentAt`	sí	`string (date-time) \| null`
`status`	sí	`pending \| sent \| failed`
`targetUrl`	sí	`string`
`updatedAt`	sí	`string (date-time)`

Errores posibles (problem+json): 400 405 422 500