Webhooks

The Webhooks API is the registration surface for outbound event callbacks. A subscription is a (url, events) pair: when one of the listed event types fires for the calling tenant (subscription.created, payment.succeeded, invoice.paid, …), the platform's webhook router POSTs the event payload to url with an HMAC signature derived from the subscription's secret.

Use this for replication into a data warehouse, for triggering downstream automations (Zapier, n8n, in-house workers), or for keeping a customer-facing app in sync without polling. Signed delivery, automatic retry with exponential back-off, and per-subscription delivery logs are all handled by the router.

Writes (POST / PATCH / DELETE) require the commerce scope; reads require read. Disabled subscriptions (isActive=false) stay in the registry but receive no deliveries.

Endpoints

GET /api/v1/webhooks

List webhook subscriptions

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/webhooks

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

isActivebooleanOptional

Filter by active status

Responses

200

Paginated list of webhook subscriptions

401

API key missing or invalid

application/json

get/webhooks

HTTPcURLJavaScriptPython

GET /api/v1/webhooks HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Returns every webhook subscription for the calling tenant (active and disabled). The response includes each subscription's url, subscribed events, isActive, last-delivery timestamp, and recent failure count for quick triage.

Requires the read scope.

POST /api/v1/webhooks

Register a webhook subscription for event callbacks. Use `GET /webhooks/event-types` to discover available event type names. Subscribing to `*` receives all events.

post

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/webhooks

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Header parameters

Idempotency-KeystringOptional

Idempotency key to safely retry without creating duplicates

Body

application/json

urlstring · uriRequired

Public HTTPS endpoint that will receive POST requests.

eventsstring[]Required

Event type names to subscribe to. Use * for all events.

Responses

201

Webhook subscription created. The response includes the secret (shown once) used to verify payloads — see signature scheme in the description.

No content

400

Validation error

application/json

post/webhooks

HTTPcURLJavaScriptPython

POST /api/v1/webhooks HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "url": "https://example.com",
  "events": [
    "text"
  ]
}

No content

Registers a new webhook subscription. url must be HTTPS in production. events is the array of event types to subscribe to — use ["*"] to receive everything, or list specific types from the registry exposed by GET /capabilities / event-types listing.

The response 201 carries the new subscription plus the per-subscription signing secret (only ever returned at create time — store it). Use it to verify the X-Signature header on incoming deliveries.

Requires the commerce scope.

DELETE /api/v1/webhooks/{id}

Delete a webhook subscription

delete

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/webhooks/{id}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Responses

204

Webhook deleted

No content

delete/webhooks/{id}

HTTPcURLJavaScriptPython

DELETE /api/v1/webhooks/{id} HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

204

Webhook deleted

No content

Permanently removes the subscription and its delivery history. To stop deliveries without losing history, prefer PATCH with isActive: false.

Requires the commerce scope. Returns 204 on success.

GET /api/v1/webhooks/{id}

Get webhook subscription details

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/webhooks/{id}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Responses

200

Webhook subscription details

No content

get/webhooks/{id}

HTTPcURLJavaScriptPython

GET /api/v1/webhooks/{id} HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

Webhook subscription details

No content

Returns the full subscription including delivery stats. The signing secret is not returned here — it is only emitted at create time. If you've lost the secret, delete the subscription and create a new one.

Requires the read scope.

PATCH /api/v1/webhooks/{id}

Update a webhook subscription

patch

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/webhooks/{id}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Body

application/json

urlstringOptional

eventsstring[]Optional

isActivebooleanOptional

Responses

200

Webhook updated

No content

patch/webhooks/{id}

HTTPcURLJavaScriptPython

PATCH /api/v1/webhooks/{id} HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "url": "text",
  "events": [
    "text"
  ],
  "isActive": true
}

200

Webhook updated

No content

Partial-update; supply only the fields you want to change. Common patterns: rotate url after a infrastructure migration, narrow events once a downstream consumer is ready for fewer event types, or flip isActive: false to pause deliveries while keeping the subscription for later.

Changing events does not retroactively redeliver missed events. Requires the commerce scope.

GET /api/v1/webhooks/{id}/deliveries

List delivery history for a webhook subscription with optional status and time-range filtering

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/webhooks/{id}/deliveries

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Webhook subscription ID

Query parameters

limitinteger · min: 1 · max: 100Optional

Max items to return (1–100, default 20)

Default: 20

offsetintegerOptional

Number of items to skip (default 0)

Default: 0

statusstring · enumOptional

Filter by delivery status (pending | retrying | delivered | dead_letter)

Possible values:

sincestring · date-timeOptional

Return deliveries created at or after this ISO 8601 timestamp

untilstring · date-timeOptional

Return deliveries created at or before this ISO 8601 timestamp

Responses

200

Paginated delivery history

application/json

404

Webhook subscription not found

application/json

get/webhooks/{id}/deliveries

HTTPcURLJavaScriptPython

GET /api/v1/webhooks/{id}/deliveries HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "webhookSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
      "eventType": "text",
      "status": "pending",
      "statusCode": 1,
      "responseBody": "text",
      "attempts": 1,
      "maxAttempts": 1,
      "lastAttemptAt": "2026-07-13T13:46:03.831Z",
      "nextRetryAt": "2026-07-13T13:46:03.831Z",
      "createdAt": "2026-07-13T13:46:03.831Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 1,
    "offset": 1,
    "hasMore": true
  }
}

Notes, examples, or caveats for GET /webhooks/{id}/deliveries go here.

GET /api/v1/webhooks/{id}/deliveries/{deliveryId}

Get a single delivery record including request payload, response body, and attempt history

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/webhooks/{id}/deliveries/{deliveryId}

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Webhook subscription ID

deliveryIdstringRequired

Delivery ID

Responses

200

Delivery record

application/json

A single webhook delivery attempt record.

idstring · uuidOptional

webhookSubscriptionIdstring · uuidOptional

eventTypestringOptional

The event type that triggered this delivery.

statusstring · enumOptional

Current delivery status. dead_letter means max retry attempts were exhausted.

Possible values:

statusCodeinteger · nullableOptional

HTTP status code returned by the consumer endpoint.

responseBodystring · nullableOptional

First 1000 chars of the consumer response body.

attemptsintegerOptional

Number of delivery attempts made so far.

maxAttemptsintegerOptional

Maximum number of attempts before dead-lettering.

lastAttemptAtstring · date-time · nullableOptional

nextRetryAtstring · date-time · nullableOptional

When the next retry is scheduled (null if delivered or dead-lettered).

createdAtstring · date-timeOptional

404

Not found

application/json

get/webhooks/{id}/deliveries/{deliveryId}

HTTPcURLJavaScriptPython

GET /api/v1/webhooks/{id}/deliveries/{deliveryId} HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "webhookSubscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "eventType": "text",
  "status": "pending",
  "statusCode": 1,
  "responseBody": "text",
  "attempts": 1,
  "maxAttempts": 1,
  "lastAttemptAt": "2026-07-13T13:46:03.831Z",
  "nextRetryAt": "2026-07-13T13:46:03.831Z",
  "createdAt": "2026-07-13T13:46:03.831Z"
}

Notes, examples, or caveats for GET /webhooks/{id}/deliveries/{deliveryId} go here.

POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/replay

Replay a delivery — re-enqueues the original payload for re-delivery. Works for any status including dead_letter.

post

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/webhooks/{id}/deliveries/{deliveryId}/replay

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Path parameters

idstringRequired

Webhook subscription ID

deliveryIdstringRequired

Delivery ID

Responses

202

Replay enqueued. The delivery will be re-attempted asynchronously and its status updated.

No content

404

Not found

application/json

post/webhooks/{id}/deliveries/{deliveryId}/replay

HTTPcURLJavaScriptPython

POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/replay HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

No content

Notes, examples, or caveats for POST /webhooks/{id}/deliveries/{deliveryId}/replay go here.

GET /api/v1/webhooks/event-types

List all supported webhook event types that can be used in subscription `events` arrays

get

https://peakcommerce.app/api/v1https://sandbox.peakcommerce.app/api/v1

/webhooks/event-types

Authorizations

ApiKeyAuthBearerAuth

X-API-KeystringRequired

Scoped API key. Scopes: read, commerce, admin.

Responses

200

List of platform-supported event types

application/json

totalintegerOptional

get/webhooks/event-types

HTTPcURLJavaScriptPython

GET /api/v1/webhooks/event-types HTTP/1.1
Host: peakcommerce.app
X-API-Key: YOUR_API_KEY
Accept: */*

200

List of platform-supported event types

{
  "data": [
    {
      "name": "text",
      "category": "text",
      "description": "text"
    }
  ],
  "total": 1
}

Notes, examples, or caveats for GET /webhooks/event-types go here.