Webhook Subscriptions

Create a webhook subscription

Creates a webhook subscription. The URL must use HTTPS and resolve to a public address. If secret is omitted, the response includes a generated secret once.

post/webhooks

Request

Base URL: https://next-api.saturation.io/v1
URL: https://next-api.saturation.io/v1/webhooks
Auth: HTTP bearer

Request body

urlstring uri required

HTTPS destination. The host must resolve to a public address.

eventsWebhookEvent[] required

One or more event types to subscribe to.

secretstring

Signing secret. When omitted, the create response includes a generated secret.

projectIdstring

A stable resource ID, such as prj_…, txn_…, or doc_….

Example request

{
  "url": "https://hooks.example.com/saturation",
  "events": [
    "transaction.created"
  ],
  "projectId": "txn_8f2a1c9e"
}

Response

The created subscription and its signing secret. Store the secret before discarding the response.

idstring required

A stable resource ID, such as prj_…, txn_…, or doc_….

urlstring uri required

HTTPS destination for deliveries. The host must resolve to a public address.

eventsWebhookEvent[] required

Event types delivered to this endpoint.

isActiveboolean required

Whether the subscription currently receives deliveries. Toggled via PATCH; a webhook continues to exist while paused.

workspaceIdstring required

A stable resource ID, such as prj_…, txn_…, or doc_….

projectIdstring

A stable resource ID, such as prj_…, txn_…, or doc_….

lastDeliveryAtstring date-time

Time of the most recent delivery attempt.

lastDeliveryStatus'pending' | 'success' | 'failed' | 'blocked' | 'dropped'

Outcome of a delivery. pending may be retried. success, failed, blocked, and dropped are final.

createdAtstring date-time required

ISO-8601 creation timestamp.

updatedAtstring date-time required

ISO-8601 last-update timestamp.

secretstring required

HMAC secret used to verify X-Saturation-Signature. Returned only when the subscription is created.

Example response

{
  "id": "txn_8f2a1c9e",
  "url": "https://hooks.example.com/saturation",
  "events": [
    "transaction.created"
  ],
  "workspaceId": "txn_8f2a1c9e",
  "projectId": "txn_8f2a1c9e",
  "secret": "whsec_example"
}

Changes

Changes to this operation have not been checked yet.