Skip to Content
API ReferenceWebhooks

Webhooks

List the webhook endpoints of the caller’s organisation and mode

GET /n/v1/webhook-endpoints

Never a secret, sealed or not, and never a capability snapshot.

Who can call it: API key or signed-in user.

Example request

bash
curl https://gp.useyona.com/n/v1/webhook-endpoints \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Errors: 401, 403, 429, 503

Create a webhook endpoint (its signing secret is shown once)

POST /n/v1/webhook-endpoints

The endpoint belongs to the organisation and MODE of the caller’s token. Each pattern is stored with the capabilities the caller holds, and delivers only the types those read.

Who can call it: Signed-in user only: do this in the Yona app.

Request body

FieldTypeRequiredDescription
urlstringYesAt most 2048 characters.
descriptionstringNoAt most 200 characters.
eventsarray of stringYesEvent patterns: an exact type, a prefix.* wildcard, or *. 1 to 100 items.

Example request

bash
curl -X POST https://gp.useyona.com/n/v1/webhook-endpoints \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/yona",
    "events": [
      "invoice.*",
      "billing.payment.succeeded"
    ]
  }'

Responses

The endpoint and its whsec_… secret — no route returns the secret again.

Errors: 400, 401, 403, 409, 429, 503

Get a webhook endpoint (never its secret)

GET /n/v1/webhook-endpoints/{id}

Who can call it: API key or signed-in user.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Example request

bash
curl https://gp.useyona.com/n/v1/webhook-endpoints/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Errors: 400, 401, 403, 404, 429, 503

Update a webhook endpoint: URL, description or patterns; enable or disable it

PATCH /n/v1/webhook-endpoints/{id}

New patterns take the editor’s capability snapshot. enabled: false stops every open delivery of the endpoint; enabled: true clears its failure run.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Request body

FieldTypeRequiredDescription
urlstringNoAt most 2048 characters.
descriptionstringNoAt most 200 characters.
eventsarray of stringNoEvent patterns: an exact type, a prefix.* wildcard, or *. 1 to 100 items.
enabledbooleanNofalse disables the endpoint (cause manual) and stops its open deliveries; true re-enables it and clears its failure run. (status itself is set by the server only.)
upgradeVersionsbooleanNoMove the endpoint to the latest version of every event type. Every type is version 1 today, so this changes nothing yet.

Example request

bash
curl -X PATCH https://gp.useyona.com/n/v1/webhook-endpoints/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      "invoice.*",
      "billing.payment.succeeded"
    ]
  }'

Responses

Errors: 400, 401, 403, 404, 429, 503

Delete a webhook endpoint

DELETE /n/v1/webhook-endpoints/{id}

Its open deliveries fail endpoint_disabled; its delivery log stays readable.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Example request

bash
curl -X DELETE https://gp.useyona.com/n/v1/webhook-endpoints/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Responses

Errors: 400, 401, 403, 404, 429, 503

Rotate a webhook endpoint’s signing secret (shown once), with an overlap window

POST /n/v1/webhook-endpoints/{id}/rotate-secret

During the overlap every request carries two v1= signatures, one per secret, so a receiver can switch without downtime.

Who can call it: Signed-in user only: do this in the Yona app.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Request body

FieldTypeRequiredDescription
overlapSecondsintegerNoHow long requests also carry a signature made with the previous secret. Default: 86400. Between 0 and 604800.

Example request

bash
curl -X POST https://gp.useyona.com/n/v1/webhook-endpoints/9f8e7d6c-5b4a-3210-fedc-ba9876543210/rotate-secret \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "overlapSeconds": 86400
  }'

Responses

Errors: 400, 401, 403, 404, 429, 503

Send a test ping, or a sample of one event type, to a webhook endpoint

POST /n/v1/webhook-endpoints/{id}/test

One delivery, "test": true, attempted once, never charged. A sample may be of any catalogue type the caller may read, whatever the endpoint subscribes to.

Who can call it: API key or signed-in user.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Request body

FieldTypeRequiredDescription
typestringNoSend a sample event of this type; when absent, a webhook_endpoint.pinged ping is sent.

Example request

bash
curl -X POST https://gp.useyona.com/n/v1/webhook-endpoints/9f8e7d6c-5b4a-3210-fedc-ba9876543210/test \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice.signed"
  }'

Responses

Errors: 400, 401, 403, 404, 429, 503

List webhook event types, with whether the caller can subscribe to each

GET /n/v1/webhook-event-types

The webhook event catalogue: type, version, family, scope, status and the capability a subscription needs. subscribable says whether the caller holds it.

Who can call it: API key or signed-in user.

Example request

bash
curl https://gp.useyona.com/n/v1/webhook-event-types \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Errors: 401, 429, 503

List logged webhook events (last 30 days)

GET /n/v1/webhook-events

The events of the caller’s mode plus the organisation-scoped ones, each with its public data; only types the caller may read.

Who can call it: API key or signed-in user.

Parameters

NameInTypeRequiredDescription
pagequeryintegerNoDefault: 1. At least 1.
limitqueryintegerNoDefault: 20. Between 1 and 100.
typequerystringNo
fromquerystring (date-time)No
toquerystring (date-time)No

Example request

bash
curl https://gp.useyona.com/n/v1/webhook-events \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Errors: 400, 401, 403, 429, 503

Get a logged webhook event

GET /n/v1/webhook-events/{id}

Who can call it: API key or signed-in user.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Example request

bash
curl https://gp.useyona.com/n/v1/webhook-events/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Errors: 400, 401, 403, 404, 429, 503

Replay a logged webhook event to one endpoint

POST /n/v1/webhook-events/{id}/redeliver

Also to an endpoint that did not receive it when it happened (disabled, or not subscribed). Never to an endpoint of a mode the event’s scope does not reach.

Who can call it: API key or signed-in user.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Request body

FieldTypeRequiredDescription
endpointIdstring (uuid)YesOne of the organisation’s endpoints in the caller’s mode.

Example request

bash
curl -X POST https://gp.useyona.com/n/v1/webhook-events/d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f/redeliver \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "endpointId": "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
  }'

Responses

Errors: 400, 401, 403, 404, 409, 429, 503

List webhook deliveries (by endpoint, status or type)

GET /n/v1/webhook-deliveries

Only deliveries of types the caller’s own capabilities could subscribe to.

Who can call it: API key or signed-in user.

Parameters

NameInTypeRequiredDescription
pagequeryintegerNoDefault: 1. At least 1.
limitqueryintegerNoDefault: 20. Between 1 and 100.
endpointIdquerystring (uuid)No
statusquerystringNoOne of pending | delivering | retrying | delivered | failed.
typequerystringNo

Example request

bash
curl https://gp.useyona.com/n/v1/webhook-deliveries \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Errors: 400, 401, 403, 429, 503

Get a webhook delivery and its attempt log

GET /n/v1/webhook-deliveries/{id}

Who can call it: API key or signed-in user.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Example request

bash
curl https://gp.useyona.com/n/v1/webhook-deliveries/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Errors: 400, 401, 403, 404, 429, 503

Redeliver a webhook delivery (one more attempt)

POST /n/v1/webhook-deliveries/{id}/redeliver

The stored bytes, to the endpoint’s current URL and secret. Appends an attempt; never rewrites one; never charged again.

Who can call it: API key or signed-in user.

Parameters

NameInTypeRequiredDescription
idpathstring (uuid)Yes

Example request

bash
curl -X POST https://gp.useyona.com/n/v1/webhook-deliveries/9f8e7d6c-5b4a-3210-fedc-ba9876543210/redeliver \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Errors: 400, 401, 403, 404, 409, 429, 503

BillingOrganizations