> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/api-groups/webhooks.md).

# 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/outbound-events`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/outbound-events" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

*Notes, examples, or caveats for `GET /outbound-events` go here.*

### `POST /api/v1/outbound-events/{id}/replay`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/outbound-events/{id}/replay" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

*Notes, examples, or caveats for `POST /outbound-events/{id}/replay` go here.*

### `GET /api/v1/outbound-events/health`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/outbound-events/health" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

*Notes, examples, or caveats for `GET /outbound-events/health` go here.*

### `GET /api/v1/webhooks`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/webhooks" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/webhooks" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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`](https://docs.peakcommerce.com/developers/api-groups/discovery.md) / 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}`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/webhooks/{id}" method="delete" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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}`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/webhooks/{id}" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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}`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/webhooks/{id}" method="patch" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/webhooks/{id}/deliveries" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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

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

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/webhooks/{id}/deliveries/{deliveryId}" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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

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

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/webhooks/{id}/deliveries/{deliveryId}/replay" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

A replay starts a fresh series of up to 9 attempts over about 3 days, with the same schedule as an original delivery. While a replay is attempting, the automatic retry schedule leaves that delivery alone, so a replay and an automatic retry never fire together. A replay is a new delivery of the same payload, so your endpoint may see the event again; process it idempotently.

Deliveries that were dead-lettered because a scheduled retry stalled for 24 hours, or because the subscription was inactive, are replayable here once the endpoint is healthy again.

### `POST /api/v1/webhooks/{id}/rotate-secret`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/webhooks/{id}/rotate-secret" method="post" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

The new secret is returned once, in this response — there is no way to fetch it again afterwards.

Rotation is designed so you never have to coordinate a simultaneous cutover:

1. Call this endpoint and store the returned `secret`.
2. Deploy it to your endpoint any time within `overlapHours` (24). Deliveries in this window carry a signature under **both** the new and the previous secret, so an endpoint still holding the old one keeps verifying normally.
3. After `previousSecretExpiresAt` passes, only the new secret signs deliveries.

Because the header can carry more than one signature, your verifier must split `X-Webhook-Signature` on commas and accept the delivery if any entry matches — see [the signature scheme](https://docs.peakcommerce.com/developers/api-reference/api-reference.md). A verifier that compares the whole header against a single digest works fine until the first rotation, then rejects every delivery for 24 hours.

### `GET /api/v1/webhooks/event-types`

{% openapi src="<https://api.peakcommerce.app/api/v1/openapi.json>" path="/webhooks/event-types" method="get" %}
<https://api.peakcommerce.app/api/v1/openapi.json>
{% endopenapi %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peakcommerce.com/developers/api-groups/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
