> 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-reference/webhooks-overview.md).

# Webhooks overview

Webhooks let your systems react to events in your PeakCommerce tenant in near real time. This page is the developer reference; for the admin UI walk-through see the Webhooks page under **Settings → Developer Tools**. For the API to manage subscriptions see [API reference: webhook subscriptions](https://docs.peakcommerce.com/developers/reference-pages/webhooks.md).

## Architecture

```
PeakCommerce
   │  (event happens)
   ▼
Webhook subscription      ── HMAC-signed POST ──▶ Your endpoint
   ▲                                                  │
   │                                       2xx within 10s
   │  (retry up to 5× on failure)                     ▼
   └────────────────────────────────────────  Delivered, recorded
```

## Delivery format

Each delivery is a `POST` with `Content-Type: application/json` and this body:

```json
{
  "id": "5d2b8f3e-6a1c-4b2e-9c3d-7e8f90a1b2c3",
  "event": "subscription.changed",
  "timestamp": "2026-05-02T14:01:23Z",
  "tenantId": "ten_01H...",
  "data": { /* the resource that changed */ }
}
```

Headers:

| Header                | Description                                                                |
| --------------------- | -------------------------------------------------------------------------- |
| `X-Webhook-Signature` | `sha256=<hex_hmac_sha256>` — HMAC of the raw body (see below)              |
| `X-Webhook-Event`     | The event type (e.g. `subscription.changed`)                               |
| `X-Webhook-Timestamp` | ISO 8601 time the delivery was first logged, the same on every retry of it |
| `X-Webhook-Id`        | The event id, the same as the body `id`                                    |

`id` identifies the **event**, not the attempt. It is identical on every retry and on a replay, so it is the key to deduplicate on: at-least-once delivery means you can receive the same event more than once. Deliveries logged before event ids existed have no `id`.

## Signature verification

Each subscription has a signing secret, returned **once** when you create it (`POST /webhooks`) — store it securely; it is never shown again.

The signature is `HMAC-SHA256(secret, rawBody)`, hex-encoded, sent in `X-Webhook-Signature` with a `sha256=` prefix. Verify it over the **raw** request body (do not parse first), using a constant-time comparison:

```python
import hmac, hashlib

def verify(secret: str, signature_header: str, raw_body: bytes) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature_header, expected)
```

Reject any request whose signature does not match, and confirm the `tenantId` in the body matches the tenant you expect.

## Event types (selected)

The `event` field carries the event type. A selection:

| Event                                                                                            | When                                                                  |
| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| `account.created`, `account.updated`                                                             | Account CRUD                                                          |
| `subscription.created`, `subscription.changed`, `subscription.cancelled`, `subscription.renewed` | Subscription lifecycle                                                |
| `order.created`, `order.updated`                                                                 | Order lifecycle                                                       |
| `payment.session_created`, `payment.succeeded`, `payment.failed`                                 | Payment lifecycle                                                     |
| `invoice.created`, `invoice.paid`, `invoice.failed`                                              | Invoice lifecycle                                                     |
| `handoff.started`, `handoff.redeemed`                                                            | Post-purchase sign-in handoff (see below)                             |
| `journey.session.refused`                                                                        | A fraud check or bot protection refused a journey session (see below) |
| `webhook.test`                                                                                   | Manually sent from the admin UI                                       |

The complete, live list is in `GET /api/v1/manifest` under `capabilities.eventTypes`.

### Which surfaces emit subscription events

`subscription.created` fires the same way whichever surface created the subscription — the admin/portal API, `POST /api/v1/subscriptions`, or a **journey purchase** (a checkout journey whose step runs the `create_subscription` commerce action). The payload shape is identical in every case, so a subscriber cannot and need not tell them apart. Journey purchases additionally carry no `userId`: the buyer is a customer, not an API user.

### Post-purchase sign-in handoff events

A completed purchase can mint a short-lived, single-use token that signs the buyer into your own app (see [Handoffs](https://docs.peakcommerce.com/developers/api-groups/handoffs.md)). Two events describe it:

| Event              | When                                                                                                              |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `handoff.started`  | PeakCommerce minted a sign-in token for a completed purchase. Carries `expiresAt`.                                |
| `handoff.redeemed` | Your app redeemed that token. Produced **once per token** — a second redemption is refused and announces nothing. |

Both carry `resourceType: "journeySession"`, the session id as `resourceId`, the `contactId`, and the `subscriptionId` the purchase created (or `null`).

**Neither event carries the token, its URL, its id, the buyer's email or their external user id.** The token is a credential and webhook payloads are logged by their recipients; the identity you need comes back in the authenticated `POST /api/v1/handoffs/redeem` response instead. Treat `handoff.started` as a notification, not as a way to obtain the token.

### Refused journey sessions

`journey.session.refused` fires when a fraud check or bot protection refuses a buyer's journey session. It is produced **once per session**, however many times the buyer retries. The same session then reads `status: "refused"` from `GET /api/v1/sessions/{id}`.

| Field                 | Value                                                                                     |
| --------------------- | ----------------------------------------------------------------------------------------- |
| `resourceType`        | `"journeySession"`                                                                        |
| `resourceId`          | The session id                                                                            |
| `journeyId`           | The journey the session belongs to                                                        |
| `externalUserId`      | Your own user id, when the session started from a verified app hand-off; otherwise `null` |
| `contactId`, `userId` | The PeakCommerce contact and user, when they exist; otherwise `null`                      |
| `action`              | `"fraud_check"` or `"bot_protection"`                                                     |
| `reason`              | Always `"refused"`                                                                        |

**The event never carries the fraud score, the signals behind it, device data, which check fired, or the buyer's email.** Use it to update your own records or to follow up with the buyer; it does not say why the buyer was refused.

### Resolved entitlements on subscription events

Subscription events carry an extra `subscription` object holding the customer's **resolved entitlement set**, so you can react to `subscription.created` without a second call to the [Entitlements API](https://docs.peakcommerce.com/developers/api-groups/entitlements.md):

```json
{
  "event": "subscription.created",
  "data": {
    "resourceType": "subscription",
    "resourceId": "…",
    "status": "active",
    "subscription": {
      "entitlements": { "max_seats": 3 },
      "resolvedFrom": { "productId": "…", "productName": "Pro" }
    }
  }
}
```

Two details worth reading carefully:

* **An absent `subscription` key is not the same as an empty one.** `entitlements: {}` means the set resolved and this plan grants nothing. A **missing** `subscription` key means the set could not be resolved for this event — treat it as "unknown" and call the Entitlements API, rather than as "no entitlements". Gating to zero on a missing key would deny a paying customer their plan.
* The same resolution rules as the API apply: `null` on a `limit` feature means **unlimited**, and `resolvedFrom` names the product the values came from (add-on products do not contribute).

### Device check result on `subscription.created`

When the checkout ran a device check through a Fingerprint integration, `subscription.created` also carries a `fraud` object with the result:

```json
{
  "event": "subscription.created",
  "data": {
    "resourceType": "subscription",
    "resourceId": "…",
    "status": "active",
    "fraud": {
      "provider": "fingerprint",
      "deviceHash": "3f0c…9a1e",
      "verdict": "allow"
    }
  }
}
```

* `verdict` is one of `allow`, `review`, `deny` or `unavailable`. `unavailable` means the check could not complete. It is never reported as `allow`.
* `deviceHash` identifies the device without revealing it: a 64-character hex HMAC-SHA256 of the device identifier with a secret kept per tenant. The same device gives the same hash within your tenant. It is `null` when the device could not be identified.
* **No `fraud` key** means no device check ran for that checkout. Treat it as "not checked", never as a pass.

## Retries & dead-lettering

* A delivery succeeds on any `2xx` response within **10 seconds**.
* On failure (non-`2xx`, network error, or timeout) the delivery is retried up to **9 attempts total** over about **3 days**. The waits after each failure are 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, 24 hours and 24 hours, each varied by up to 10% so a burst of retries is spread out. A retry may arrive a few seconds after its scheduled time.
* Retries are **durable**: each retry is scheduled on the delivery record (`nextRetryAt`), not held in memory, so a PeakCommerce deploy or restart does not lose it.
* A delivery is marked **`dead_letter`**, with the reason in `errorMessage`, when:

  * the 9th attempt fails;
  * a scheduled retry has not run within **24 hours** of its due time (retries stalled);
  * its webhook subscription has been deleted or deactivated (it is not retried).

  Dead-lettered deliveries are recorded under **Admin → Webhooks → Deliveries**.
* List dead-lettered deliveries with `GET /api/v1/webhooks/{id}/deliveries?status=dead_letter`, and re-enqueue any of them with `POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/replay`.

## Best practices

* **Respond quickly** — return a `2xx` within 10 seconds. Move slow work to a queue.
* **Be idempotent** — deliveries may be retried, so process the same event safely more than once. Record the `id` (or `X-Webhook-Id`) of each event you have handled and skip one you have already seen.
* **Verify the signature on every request.**
* **Don't assume ordering** — events may arrive out of order; use the resource's own `updatedAt` / `timestamp` as your watermark.

## Related

* Webhooks (admin app: **Settings → Developer Tools → Webhooks**)
* [API reference: webhook subscriptions](https://docs.peakcommerce.com/developers/reference-pages/webhooks.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/developers/api-reference/webhooks-overview.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.
