Webhooks · Compense Docs

Esta página se genera desde el contrato (data/gateway-v1.json): cada operación muestra su verbo, ruta, parámetros, cuerpo, respuestas, si lleva Idempotency-Key y el método equivalente en los cinco SDK. Para el flujo de punta a punta con ejemplos completos, ve a la guía de implementación.

Operaciones del tag `webhooks` #

Descripción en el contrato: Self-service outbound webhooks for the API key’s organization: event catalog (with payload examples and the HMAC signature contract), endpoint CRUD, secret rotation, signed test events, and delivery history with replay. Scopes: webhooks:read (reads) and webhooks:manage (writes).

Método	Ruta	Operación	Scope	Idem.
GET	`/v1/gateway/webhooks/deliveries/`	List deliveries (filters: status, event, endpoint, dates)	`webhooks:read`	—
GET	`/v1/gateway/webhooks/deliveries/{delivery_id}/`	Delivery detail (attempts, response; no secret)	`webhooks:read`	—
POST	`/v1/gateway/webhooks/deliveries/{delivery_id}/replay/`	Replay a failed or abandoned delivery	`webhooks:manage`	recomendada
GET	`/v1/gateway/webhooks/endpoints/`	List the organization's endpoints	`webhooks:read`	—
POST	`/v1/gateway/webhooks/endpoints/`	Register an endpoint (returns the secret ONCE)	`webhooks:manage`	recomendada
GET	`/v1/gateway/webhooks/endpoints/{endpoint_id}/`	Endpoint detail	`webhooks:read`	—
PATCH	`/v1/gateway/webhooks/endpoints/{endpoint_id}/`	Update an endpoint (url, events, label, description, active)	`webhooks:manage`	recomendada
DELETE	`/v1/gateway/webhooks/endpoints/{endpoint_id}/`	Delete an endpoint (and its delivery history)	`webhooks:manage`	recomendada
POST	`/v1/gateway/webhooks/endpoints/{endpoint_id}/rotate-secret/`	Rotate the signing secret (the old one stops working immediately)	`webhooks:manage`	recomendada
POST	`/v1/gateway/webhooks/endpoints/{endpoint_id}/test/`	Send a signed test event	`webhooks:manage`	recomendada
GET	`/v1/gateway/webhooks/event-catalog/`	Event catalog (description, payload example, signature contract)	`webhooks:read`	—

List deliveries (filters: status, event, endpoint, dates) #

GET/v1/gateway/webhooks/deliveries/

operationId listWebhookDeliveries
Autenticación X-API-Key · scope webhooks:read
Idempotency-Key no aplica

Parámetros

Nombre	En	Tipo	Descripción
`status`	query	string	Delivery status.
`event_type`	query	string	Catalog key, e.g. credits.decision.
`endpoint_id`	query	string	Only deliveries of this endpoint.
`date_from`	query	string	From (YYYY-MM-DD or ISO-8601), by queue time.
`date_to`	query	string	To (YYYY-MM-DD or ISO-8601), inclusive.
`page`	query	integer	Page (1-based).
`page_size`	query	integer	Page size.

Respuestas

Código	Descripción	Cuerpo
200	A page of deliveries.	`WebhookDeliveryList` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.deliveries.list()

client.webhooks.deliveries.list()

$client->webhooks->deliveries->list()

await client.Webhooks.Deliveries.ListAsync()

client.Webhooks.Deliveries.List(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/deliveries/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Delivery detail (attempts, response; no secret) #

GET/v1/gateway/webhooks/deliveries/{delivery_id}/

operationId getWebhookDelivery
Autenticación X-API-Key · scope webhooks:read
Idempotency-Key no aplica

Parámetros

Nombre	En	Tipo	Descripción
`delivery_id` obligatorio	ruta	string	Webhook delivery id. Ej.: `7c9e6679-7425-40de-944b-e07fc1f90ae7`

Respuestas

Código	Descripción	Cuerpo
200	The delivery.	`WebhookDeliveryDetail` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.deliveries.get()

client.webhooks.deliveries.get()

$client->webhooks->deliveries->get()

await client.Webhooks.Deliveries.GetAsync()

client.Webhooks.Deliveries.Get(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/deliveries/7c9e6679-7425-40de-944b-e07fc1f90ae7/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Replay a failed or abandoned delivery #

POST/v1/gateway/webhooks/deliveries/{delivery_id}/replay/

operationId replayWebhookDelivery
Autenticación X-API-Key · scope webhooks:manage
Idempotency-Key recomendada (el SDK la genera)

Parámetros

Nombre	En	Tipo	Descripción
`delivery_id` obligatorio	ruta	string	Webhook delivery id. Ej.: `7c9e6679-7425-40de-944b-e07fc1f90ae7`
`Idempotency-Key`	cabecera	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. Ej.: `horizonte-2026-06-26-credit-000123`

Respuestas

Código	Descripción	Cuerpo
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.deliveries.replay()

client.webhooks.deliveries.replay()

$client->webhooks->deliveries->replay()

await client.Webhooks.Deliveries.ReplayAsync()

client.Webhooks.Deliveries.Replay(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/deliveries/7c9e6679-7425-40de-944b-e07fc1f90ae7/replay/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

List the organization's endpoints #

GET/v1/gateway/webhooks/endpoints/

operationId listWebhookEndpoints
Autenticación X-API-Key · scope webhooks:read
Idempotency-Key no aplica

Respuestas

Código	Descripción	Cuerpo
200	Endpoints (no secrets).	`WebhookEndpointList` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.endpoints.list()

client.webhooks.endpoints.list()

$client->webhooks->endpoints->list()

await client.Webhooks.Endpoints.ListAsync()

client.Webhooks.Endpoints.List(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/endpoints/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Register an endpoint (returns the secret ONCE) #

POST/v1/gateway/webhooks/endpoints/

operationId createWebhookEndpoint
Autenticación X-API-Key · scope webhooks:manage
Idempotency-Key recomendada (el SDK la genera)

data.secret is shown only in this response (and on rotate-secret). An idempotent replay returns the endpoint without the secret.

Parámetros

Nombre	En	Tipo	Descripción
`Idempotency-Key`	cabecera	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. Ej.: `horizonte-2026-06-26-credit-000123`

Cuerpo de la petición

Tipo de contenido: application/json · obligatorio

Esquema WebhookEndpointCreateIn

Campo	Tipo	Descripción
`active`	boolean
`description`	string
`events` obligatorio	array de string	Keys from the event catalog. Ej.: `["credits.decision","wallets.cashin.confirmed"]`
`label`	string	Máx. 128 caracteres.
`url` obligatorio	string (uri)	Public HTTPS URL. Ej.: `"https://erp.nova.example/compense/webhooks"`

Respuestas

Código	Descripción	Cuerpo
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.endpoints.create()

client.webhooks.endpoints.create()

$client->webhooks->endpoints->create()

await client.Webhooks.Endpoints.CreateAsync()

client.Webhooks.Endpoints.Create(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/endpoints/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.nova.example/compense/webhooks",
    "events": [
      "credits.decision",
      "wallets.cashin.confirmed"
    ]
  }'

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Endpoint detail #

GET/v1/gateway/webhooks/endpoints/{endpoint_id}/

operationId getWebhookEndpoint
Autenticación X-API-Key · scope webhooks:read
Idempotency-Key no aplica

Parámetros

Nombre	En	Tipo	Descripción
`endpoint_id` obligatorio	ruta	string	Webhook endpoint id. Ej.: `3f1a2b3c-0000-4a1b-9c2d-000000000001`

Respuestas

Código	Descripción	Cuerpo
200	The endpoint (no secret).	`WebhookEndpoint` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.endpoints.get()

client.webhooks.endpoints.get()

$client->webhooks->endpoints->get()

await client.Webhooks.Endpoints.GetAsync()

client.Webhooks.Endpoints.Get(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/endpoints/3f1a2b3c-0000-4a1b-9c2d-000000000001/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Update an endpoint (url, events, label, description, active) #

PATCH/v1/gateway/webhooks/endpoints/{endpoint_id}/

operationId updateWebhookEndpoint
Autenticación X-API-Key · scope webhooks:manage
Idempotency-Key recomendada (el SDK la genera)

Parámetros

Nombre	En	Tipo	Descripción
`endpoint_id` obligatorio	ruta	string	Webhook endpoint id. Ej.: `3f1a2b3c-0000-4a1b-9c2d-000000000001`
`Idempotency-Key`	cabecera	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. Ej.: `horizonte-2026-06-26-credit-000123`

Cuerpo de la petición

Tipo de contenido: application/json · obligatorio

Esquema WebhookEndpointUpdateIn — Partial update. Only these fields are accepted.

Campo	Tipo	Descripción
`active`	boolean
`description`	string
`events`	array de string
`label`	string	Máx. 128 caracteres.
`url`	string (uri)

Respuestas

Código	Descripción	Cuerpo
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.endpoints.update()

client.webhooks.endpoints.update()

$client->webhooks->endpoints->update()

await client.Webhooks.Endpoints.UpdateAsync()

client.Webhooks.Endpoints.Update(ctx, …)

curl -X PATCH "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/endpoints/3f1a2b3c-0000-4a1b-9c2d-000000000001/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Delete an endpoint (and its delivery history) #

DELETE/v1/gateway/webhooks/endpoints/{endpoint_id}/

operationId deleteWebhookEndpoint
Autenticación X-API-Key · scope webhooks:manage
Idempotency-Key recomendada (el SDK la genera)

Parámetros

Nombre	En	Tipo	Descripción
`endpoint_id` obligatorio	ruta	string	Webhook endpoint id. Ej.: `3f1a2b3c-0000-4a1b-9c2d-000000000001`
`Idempotency-Key`	cabecera	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. Ej.: `horizonte-2026-06-26-credit-000123`

Respuestas

Código	Descripción	Cuerpo
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.endpoints.delete()

client.webhooks.endpoints.delete()

$client->webhooks->endpoints->delete()

await client.Webhooks.Endpoints.DeleteAsync()

client.Webhooks.Endpoints.Delete(ctx, …)

curl -X DELETE "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/endpoints/3f1a2b3c-0000-4a1b-9c2d-000000000001/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Rotate the signing secret (the old one stops working immediately) #

POST/v1/gateway/webhooks/endpoints/{endpoint_id}/rotate-secret/

operationId rotateWebhookSecret
Autenticación X-API-Key · scope webhooks:manage
Idempotency-Key recomendada (el SDK la genera)

Parámetros

Nombre	En	Tipo	Descripción
`endpoint_id` obligatorio	ruta	string	Webhook endpoint id. Ej.: `3f1a2b3c-0000-4a1b-9c2d-000000000001`
`Idempotency-Key`	cabecera	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. Ej.: `horizonte-2026-06-26-credit-000123`

Respuestas

Código	Descripción	Cuerpo
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.endpoints.rotate_secret()

client.webhooks.endpoints.rotateSecret()

$client->webhooks->endpoints->rotateSecret()

await client.Webhooks.Endpoints.RotateSecretAsync()

client.Webhooks.Endpoints.RotateSecret(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/endpoints/3f1a2b3c-0000-4a1b-9c2d-000000000001/rotate-secret/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Send a signed test event #

POST/v1/gateway/webhooks/endpoints/{endpoint_id}/test/

operationId sendWebhookTestEvent
Autenticación X-API-Key · scope webhooks:manage
Idempotency-Key recomendada (el SDK la genera)

Payload carries "test": true and the event_id starts with test-.

Parámetros

Nombre	En	Tipo	Descripción
`endpoint_id` obligatorio	ruta	string	Webhook endpoint id. Ej.: `3f1a2b3c-0000-4a1b-9c2d-000000000001`
`Idempotency-Key`	cabecera	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. Ej.: `horizonte-2026-06-26-credit-000123`

Cuerpo de la petición

Tipo de contenido: application/json

Esquema WebhookTestIn

Campo	Tipo	Descripción
`event_type`	string	Catalog key whose payload_example is sent (default test.ping). Ej.: `"credits.decision"`

Respuestas

Código	Descripción	Cuerpo
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.endpoints.send_test()

client.webhooks.endpoints.sendTest()

$client->webhooks->endpoints->sendTest()

await client.Webhooks.Endpoints.SendTestAsync()

client.Webhooks.Endpoints.SendTest(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/endpoints/3f1a2b3c-0000-4a1b-9c2d-000000000001/test/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "credits.decision"
  }'

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Event catalog (description, payload example, signature contract) #

GET/v1/gateway/webhooks/event-catalog/

operationId getWebhookEventCatalog
Autenticación X-API-Key · scope webhooks:read
Idempotency-Key no aplica

Parámetros

Nombre	En	Tipo	Descripción
`category`	query	string	Filter by category (credits, wallets, …).

Respuestas

Código	Descripción	Cuerpo
200	The catalog.	`WebhookEventCatalog` application/json

Errores posibles (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

Ver Errores problem+json para la excepción equivalente en cada SDK.

Ejemplo

Método del SDK y petición HTTP

client.webhooks.event_catalog()

client.webhooks.eventCatalog()

$client->webhooks->eventCatalog()

await client.Webhooks.EventCatalogAsync()

client.Webhooks.EventCatalog(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/webhooks/event-catalog/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Los métodos de cada SDK salen de su suite de paridad con el contrato. El cURL va contra el sandbox; los valores <campo> son marcadores.

Operaciones del tag webhooks #

List deliveries (filters: status, event, endpoint, dates) #

Parámetros

Respuestas

Ejemplo

Delivery detail (attempts, response; no secret) #

Parámetros

Respuestas

Ejemplo

Replay a failed or abandoned delivery #

Parámetros

Respuestas

Ejemplo

List the organization's endpoints #

Respuestas

Ejemplo

Register an endpoint (returns the secret ONCE) #

Parámetros

Cuerpo de la petición

Respuestas

Ejemplo

Endpoint detail #

Parámetros

Respuestas

Ejemplo

Update an endpoint (url, events, label, description, active) #

Parámetros

Cuerpo de la petición

Respuestas

Ejemplo

Delete an endpoint (and its delivery history) #

Parámetros

Respuestas

Ejemplo

Rotate the signing secret (the old one stops working immediately) #

Parámetros

Respuestas

Ejemplo

Send a signed test event #

Parámetros

Cuerpo de la petición

Respuestas

Ejemplo

Event catalog (description, payload example, signature contract) #

Parámetros

Respuestas

Ejemplo

Operaciones del tag `webhooks` #