> 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/webhooks`

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/webhooks" method="get" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/webhooks" method="post" %}
<https://api.peakcommerce.com/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`](/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.com/api/v1/openapi.json>" path="/webhooks/{id}" method="delete" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/webhooks/{id}" method="get" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/webhooks/{id}" method="patch" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/webhooks/{id}/deliveries" method="get" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/webhooks/{id}/deliveries/{deliveryId}" method="get" %}
<https://api.peakcommerce.com/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.com/api/v1/openapi.json>" path="/webhooks/{id}/deliveries/{deliveryId}/replay" method="post" %}
<https://api.peakcommerce.com/api/v1/openapi.json>
{% endopenapi %}

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

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

{% openapi src="<https://api.peakcommerce.com/api/v1/openapi.json>" path="/webhooks/event-types" method="get" %}
<https://api.peakcommerce.com/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.