> 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/product/settings/developer-tools/webhooks.md).

# Webhooks

**Settings → Webhooks** manages outbound **webhook subscriptions** so your systems receive PeakCommerce events in real time instead of polling the API.

## Why it matters

Webhooks let you react to commerce activity the moment it happens — a new subscription, a completed order, a payment — by pushing a signed JSON payload to an endpoint you control.

## Tabs

* **Subscriptions** — register an endpoint with **Add Webhook**: a public **HTTPS endpoint URL** and the **events** it should receive. Subscribe to specific event types, or use `*` to receive all of them. Each subscription's actions menu lets you **Pause**, **Resume**, **Reveal signing secret**, **Rotate signing secret**, or **Delete** it.
* **Delivery Log** — review recent deliveries with their status, HTTP response code, and attempt history to troubleshoot a failing endpoint.

## Delivery format

Each delivery is an HTTP `POST` with a JSON body:

```json
{ "event": "<event type>", "timestamp": "<ISO 8601>", "tenantId": "<your tenant>", "data": { } }
```

Headers sent with every request:

| Header                | Value                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `X-Webhook-Signature` | One or more comma-separated `sha256=<hmac>` values — HMAC-SHA256 of the **raw request body**, one per active signing secret |
| `X-Webhook-Event`     | the event type name                                                                                                         |
| `X-Webhook-Timestamp` | ISO 8601 timestamp of the event                                                                                             |

## Verification and security

* **Verify the signature.** Compute `HMAC-SHA256(secret, rawBody)` over the *unparsed* body and hex-encode it. Split `X-Webhook-Signature` on commas and accept the delivery if **any** entry equals `sha256=<your digest>`, using a constant-time comparison.
* **Always split on commas, even if you never rotate.** While a rotation is in progress the header carries a signature under each active secret. A verifier that compares the whole header against one digest rejects every delivery until the overlap ends.
* **Keep the signing secret safe.** It is shown when you create the subscription, and you can show it again with **Reveal signing secret** from the subscription's actions menu.
* **Use a public HTTPS endpoint.** When you add or edit a subscription, the URL must use `https://`; an `http://` address, a loopback address, or a private network address is refused with the reason. Return a `2xx` quickly to acknowledge receipt.

## Rotating the signing secret

Choose **Rotate signing secret** from the subscription's actions menu. The new secret signs deliveries straight away, and the previous secret keeps being signed alongside it for **24 hours**. Deploy the new secret to your endpoint any time inside that window — because your verifier accepts any matching entry, no delivery is dropped. After the window closes, only the new secret is used.

## Retries and dead-lettering

Failed deliveries are retried with increasing waits over **about 3 days**: 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours and 24 hours, for **9 attempts** in all. After the ninth failure the delivery is marked **`dead_letter`**, visible in the Delivery Log for diagnosis and replay. Every failed attempt is recorded in the Delivery Log as it happens.

For the full event-type catalog, payload schemas, and replay endpoints, see the Webhooks reference in the **Developers** space. Related: [API Keys](https://docs.peakcommerce.com/product/settings/developer-tools/api-keys.md).


---

# 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/product/settings/developer-tools/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.
