Webhooks · Compense Docs

This page is generated from the contract (data/gateway-v1.json): each operation shows its verb, path, parameters, body, responses, whether it carries an Idempotency-Key, and the equivalent method in all five SDKs. For the end-to-end flow with complete examples, see the implementation guide.

Operations in tag `webhooks` #

Contract description: 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).

Method	Path	Operation	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`	recommended
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`	recommended
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`	recommended
DELETE	`/v1/gateway/webhooks/endpoints/{endpoint_id}/`	Delete an endpoint (and its delivery history)	`webhooks:manage`	recommended
POST	`/v1/gateway/webhooks/endpoints/{endpoint_id}/rotate-secret/`	Rotate the signing secret (the old one stops working immediately)	`webhooks:manage`	recommended
POST	`/v1/gateway/webhooks/endpoints/{endpoint_id}/test/`	Send a signed test event	`webhooks:manage`	recommended
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
Authentication X-API-Key · scope webhooks:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`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.

Responses

Code	Description	Body
200	A page of deliveries.	`WebhookDeliveryList` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Delivery detail (attempts, response; no secret) #

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

operationId getWebhookDelivery
Authentication X-API-Key · scope webhooks:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`delivery_id` required	path	string	Webhook delivery id. E.g.: `7c9e6679-7425-40de-944b-e07fc1f90ae7`

Responses

Code	Description	Body
200	The delivery.	`WebhookDeliveryDetail` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Replay a failed or abandoned delivery #

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

operationId replayWebhookDelivery
Authentication X-API-Key · scope webhooks:manage
Idempotency-Key recommended (the SDK generates it)

Parameters

Name	In	Type	Description
`delivery_id` required	path	string	Webhook delivery id. E.g.: `7c9e6679-7425-40de-944b-e07fc1f90ae7`
`Idempotency-Key`	header	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. E.g.: `horizonte-2026-06-26-credit-000123`

Responses

Code	Description	Body
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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)"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

List the organization's endpoints #

GET/v1/gateway/webhooks/endpoints/

operationId listWebhookEndpoints
Authentication X-API-Key · scope webhooks:read
Idempotency-Key not applicable

Responses

Code	Description	Body
200	Endpoints (no secrets).	`WebhookEndpointList` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Register an endpoint (returns the secret ONCE) #

POST/v1/gateway/webhooks/endpoints/

operationId createWebhookEndpoint
Authentication X-API-Key · scope webhooks:manage
Idempotency-Key recommended (the SDK generates it)

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

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	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. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Schema WebhookEndpointCreateIn

Field	Type	Description
`active`	boolean
`description`	string
`events` required	array of string	Keys from the event catalog. E.g.: `["credits.decision","wallets.cashin.confirmed"]`
`label`	string	Max. 128 characters.
`url` required	string (uri)	Public HTTPS URL. E.g.: `"https://erp.nova.example/compense/webhooks"`

Responses

Code	Description	Body
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Endpoint detail #

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

operationId getWebhookEndpoint
Authentication X-API-Key · scope webhooks:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`endpoint_id` required	path	string	Webhook endpoint id. E.g.: `3f1a2b3c-0000-4a1b-9c2d-000000000001`

Responses

Code	Description	Body
200	The endpoint (no secret).	`WebhookEndpoint` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

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

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

operationId updateWebhookEndpoint
Authentication X-API-Key · scope webhooks:manage
Idempotency-Key recommended (the SDK generates it)

Parameters

Name	In	Type	Description
`endpoint_id` required	path	string	Webhook endpoint id. E.g.: `3f1a2b3c-0000-4a1b-9c2d-000000000001`
`Idempotency-Key`	header	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. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

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

Field	Type	Description
`active`	boolean
`description`	string
`events`	array of string
`label`	string	Max. 128 characters.
`url`	string (uri)

Responses

Code	Description	Body
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Delete an endpoint (and its delivery history) #

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

operationId deleteWebhookEndpoint
Authentication X-API-Key · scope webhooks:manage
Idempotency-Key recommended (the SDK generates it)

Parameters

Name	In	Type	Description
`endpoint_id` required	path	string	Webhook endpoint id. E.g.: `3f1a2b3c-0000-4a1b-9c2d-000000000001`
`Idempotency-Key`	header	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. E.g.: `horizonte-2026-06-26-credit-000123`

Responses

Code	Description	Body
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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)"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

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

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

operationId rotateWebhookSecret
Authentication X-API-Key · scope webhooks:manage
Idempotency-Key recommended (the SDK generates it)

Parameters

Name	In	Type	Description
`endpoint_id` required	path	string	Webhook endpoint id. E.g.: `3f1a2b3c-0000-4a1b-9c2d-000000000001`
`Idempotency-Key`	header	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. E.g.: `horizonte-2026-06-26-credit-000123`

Responses

Code	Description	Body
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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)"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Send a signed test event #

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

operationId sendWebhookTestEvent
Authentication X-API-Key · scope webhooks:manage
Idempotency-Key recommended (the SDK generates it)

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

Parameters

Name	In	Type	Description
`endpoint_id` required	path	string	Webhook endpoint id. E.g.: `3f1a2b3c-0000-4a1b-9c2d-000000000001`
`Idempotency-Key`	header	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. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json

Schema WebhookTestIn

Field	Type	Description
`event_type`	string	Catalog key whose payload_example is sent (default test.ping). E.g.: `"credits.decision"`

Responses

Code	Description	Body
200	Done; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

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

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

operationId getWebhookEventCatalog
Authentication X-API-Key · scope webhooks:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`category`	query	string	Filter by category (credits, wallets, …).

Responses

Code	Description	Body
200	The catalog.	`WebhookEventCatalog` application/json

Possible errors (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`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

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"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Operations in tag webhooks #

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

Parameters

Responses

Example

Delivery detail (attempts, response; no secret) #

Parameters

Responses

Example

Replay a failed or abandoned delivery #

Parameters

Responses

Example

List the organization's endpoints #

Responses

Example

Register an endpoint (returns the secret ONCE) #

Parameters

Request body

Responses

Example

Endpoint detail #

Parameters

Responses

Example

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

Parameters

Request body

Responses

Example

Delete an endpoint (and its delivery history) #

Parameters

Responses

Example

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

Parameters

Responses

Example

Send a signed test event #

Parameters

Request body

Responses

Example

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

Parameters

Responses

Example

Operations in tag `webhooks` #