> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference.md).

# Webhook Event Reference

Webhook notifications let your backend react to changes without polling. This page is the shared operational reference for Bead webhook delivery.

Bead has two webhook families:

* **Payment webhooks** report payment status changes and reclaim progress. They are configured per terminal, or per payment.
* **Partner webhooks** report partner level activity: onboarding application events, settlement events, and reclaim events. They are configured once per partner.

Both families sign every delivery with the same `X-Webhook-Signature` standard.

Use this page for:

* delivery behavior and retries
* signature verification
* idempotent processing
* ordering and replay safety
* production operating guidance

Use the product specific webhook page for:

* setup and registration steps
* payload fields and examples
* event types or status meanings
* product specific business handling

**What this page does and does not define**

This page defines the shared operational model for webhook handling.

This page does **not** define a single canonical payload schema for every webhook family. Payload shape is product specific. Do not assume a shared cross product envelope unless the relevant product page explicitly documents one.

**Where events go**

**Payment webhooks**

Bead supports two payment webhook delivery paths:

* **Terminal default webhook**: configured at the terminal level. Applies to all payments created by that terminal.
* **Per payment webhook URLs**: supplied through `webhookUrls` on `POST /Payments` (also accepted on the deprecated `POST /Payments/crypto`). Applies only to that individual payment.

When both are present, Bead fans out the same payment event to the terminal webhook and to each URL listed in `webhookUrls`.

**Partner webhooks**

Partner webhooks cover activity at the partner level. Today that means application events (viewed, signed, reviewed, changes requested, merchant boarded), settlement events (settlement held), and reclaim events (reclaim status changed). A partner has a single webhook endpoint and a single secret, and every registered event type is delivered to that endpoint.

Partner webhooks are registered with `PUT /merchant-onboarding/{partnerId}/webhook`. See [Partner Webhooks](https://developers.bead.xyz/onboarding/partner-webhooks.md) for setup, event types, and payload fields.

**Configure the terminal default webhook**

Payment webhooks are configured at the terminal level. The following endpoints manage the terminal's webhook URL:

* `PUT /Terminals/{id}/webhook`: set or update the terminal webhook URL
* `DELETE /Terminals/{id}/webhook`: remove the terminal webhook URL

**Authentication**

Use your **admin API key** in the `X-Api-Key` header for terminal webhook management. These endpoints do not accept a terminal payments API key. Using a terminal payments API key will return `403 Forbidden`.

**Request headers**

| Header         | Value              |
| -------------- | ------------------ |
| `X-Api-Key`    | `{adminApiKey}`    |
| `Content-Type` | `application/json` |
| `Accept`       | `application/json` |

**Request body**

| Field | Type         | Required | Description                                                                                                       |
| ----- | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `url` | string (URI) | Yes      | Fully qualified HTTPS URL where terminal level payment status events should be delivered. Maximum 512 characters. |

**Example request**

```bash
curl --request PUT "https://api.test.devs.beadpay.io/Terminals/{id}/webhook" \
--header "X-Api-Key: {adminApiKey}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
"url": "https://yourapp.com/webhooks/payment-status"
}'
```

**Example response**

```json
{
"url": "https://yourapp.com/webhooks/payment-status",
"signingSecret": "{base64EncodedSecret}"
}
```

Store `signingSecret` securely. Use it to verify the `X-Webhook-Signature` header on all incoming webhook deliveries for this terminal. Treat it like a password and do not log it or expose it in client side code.

**Notes**

* Use an HTTPS endpoint.
* The request body field is `url`, not `webhookUrl`.
* If you do not manage terminal configuration directly, coordinate with Bead support using your `terminalId` and the desired webhook URL.

**Signature header**

Every Bead webhook delivery, payment or partner, carries an `X-Webhook-Signature` header. The header format and the signed message are identical across both families. What differs is the secret and how it becomes the HMAC key:

| Family                        | Secret                            | HMAC key                                                                           |
| ----------------------------- | --------------------------------- | ---------------------------------------------------------------------------------- |
| Payment and terminal webhooks | `signingSecret`, one per terminal | The base64 decoded bytes of the `signingSecret`                                    |
| Partner webhooks              | `webhookSecret`, one per partner  | The UTF-8 bytes of the `webhookSecret` exactly as issued. Do not base64 decode it. |

Partner webhooks also continue to send the legacy `X-Bead-Signature` header for integrations that already verify it. See [How do I verify that a webhook really came from Bead?](https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-verify-that-a-webhook-really-came-from-bead.md) for details on the legacy header.

For payment webhooks, `X-Webhook-Signature` is included on **both** terminal level deliveries and per payment deliveries sent to `webhookUrls`. Both delivery paths use the same terminal's `signingSecret` and the same signing logic, but each individual delivery is signed with its own fresh timestamp, so the signature value differs per delivery even when the JSON body sent to multiple destinations is identical.

**For payment webhooks, this depends on the terminal having a `signingSecret` configured.** A terminal only gets a `signingSecret` once you have called `PUT /Terminals/{id}/webhook` on it at least once. If a terminal has never had a webhook configured this way, it has no `signingSecret`, and any `webhookUrls` deliveries for payments on that terminal are sent **without** an `X-Webhook-Signature` header, silently, with no error or warning surfaced anywhere. If your integration relies on `webhookUrls` rather than the terminal's own default URL, set a terminal level webhook at least once to establish the secret before you depend on signature verification.

Example:

```
X-Webhook-Signature: t=1781811428956,s=FK/SW9lIK0CXpNnfweTN3ZbJ8Nvbm1RF69Nm6XE8w3O=
```

| Field | Description                                                                                                                         |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `t`   | Unix epoch timestamp in **milliseconds** when Bead generated the event                                                              |
| `s`   | **Base64 encoded** HMAC-SHA256 digest of the signed message `t + "." + rawBody`, computed with the HMAC key for your webhook family |

Always verify the signature against the **raw request body** before parsing or processing JSON.

**Signature verification flow**

1. Read the raw request body exactly as received. Do not parse or reserialize JSON before this step.
2. Read the `X-Webhook-Signature` header and parse the `t` and `s` values. Split each part on the first `=` only, because `s` ends with `=` padding.
3. Validate the timestamp by confirming `t` (in milliseconds) is within your allowed freshness window. A 5 minute skew limit is recommended to prevent replay attacks.
4. Build the HMAC key for your family. For payment webhooks, base64 decode the terminal `signingSecret`. For partner webhooks, use the partner `webhookSecret` as UTF-8 bytes.
5. Construct the signed message by concatenating `t`, a literal period, and the raw request body: `message = t + "." + rawBody`.
6. Compute `HMAC-SHA256(key, message)` and base64 encode the digest.
7. Compare your computed base64 digest to `s` using a constant time comparison. Reject the request if they do not match.
8. Only then parse and process the JSON body.

For full code examples for both families, see [How do I verify that a webhook really came from Bead?](https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/how-do-i-verify-that-a-webhook-really-came-from-bead.md)

**Delivery mechanics**

* **Method:** HTTP `POST`
* **Content type:** `application/json`
* **Success condition:** a `2xx` response, preferably `200 OK`
* **Timeout:** 10 seconds per attempt
* **Retry behavior for payment webhooks:** exponential backoff for up to approximately 24 hours if a `2xx` response is not returned
* **Retry behavior for partner webhooks:** if your endpoint returns `5xx` or `408`, or cannot be reached, Bead retries up to 5 times with exponential backoff, at roughly 2, 4, 8, 16, and 32 seconds, and then drops the delivery. See [Partner Webhooks](https://developers.bead.xyz/onboarding/partner-webhooks.md).
* **Delivery model:** at least once
* **Ordering:** do not assume perfect ordering
* **One event per change:** payment webhooks send one event per `statusCode` change and one event per `refundLifecycleStatus` change

If your endpoint does not return a `2xx` response quickly, Bead may retry the same event.

**Recommended processing model**

1. Accept the request.
2. Preserve the raw body and headers.
3. Verify the signature.
4. Parse the JSON payload.
5. Build an idempotency key from the identifiers in the payload.
6. Persist or enqueue the event.
7. Apply business logic asynchronously if needed.
8. Return a `2xx` response quickly.

**Idempotency and duplicate handling**

Treat webhook delivery as at least once.

If a webhook family does not provide a dedicated `eventId`, derive idempotency from the identifiers in the payload.

For payment webhooks, a practical idempotency key is `paymentId` + `statusCode` + `refundLifecycleStatus`, with `receivedTime` optionally included for debugging. Reclaim progress events carry the payment's final `statusCode`, so a key without `refundLifecycleStatus` would treat them as duplicates. `trackingId` is deprecated and should not be used as part of the key, even though it is still present on the payload for backward compatibility.

For partner webhooks, application events carry an event `id` you can use as the key. Settlement events generate a new `id` on every send, so use `settlementId` + `type` for those. Reclaim events also generate a new `id` on every send, so use `paymentId` + `data.refundLifecycleStatus` for those.

Do not treat duplicate deliveries as errors. They are a normal part of retry safe webhook delivery.

**Ordering and state convergence**

Do not assume events arrive in perfect order.

Your handler should compare the incoming event to your current known state, ignore older or duplicate state transitions when appropriate, and converge on the latest valid state.

If you need to confirm the latest current state, call the relevant read endpoint for that product area. For payments, use `GET /Payments/{paymentId}/tracking`.

**Security checklist**

* Use HTTPS webhook endpoints.
* Verify `X-Webhook-Signature` on every request where it is present.
* For payment webhooks, set a terminal level webhook at least once so a `signingSecret` exists, even if `webhookUrls` is your main delivery path. Otherwise those deliveries arrive unsigned.
* For partner webhooks, use the `webhookSecret` as UTF-8 bytes. Do not base64 decode it.
* Treat signing secrets like passwords.
* Reject malformed or unsigned requests.
* Reject stale timestamps to reduce replay risk.
* Avoid logging secrets or full sensitive headers.
* Keep development, staging, and production webhook URLs separate.
* Do not rely on source IP allowlisting alone. Signature verification should be your primary trust control.

**Operational checklist**

* Return a `2xx` response quickly.
* Queue or persist work before heavy downstream processing.
* Instrument request logging and delivery failures.
* Track retry volume and error rates.
* Build idempotent consumers.
* Test both happy path and non happy path events in sandbox.

**Product specific pages**

Use the product area webhook page for payload fields, examples, and business handling:

* [Payment Webhooks](https://developers.bead.xyz/payments/payment-webhooks.md)
* [Partner Webhooks](https://developers.bead.xyz/onboarding/partner-webhooks.md)
* [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md)

**Forward compatibility**

New webhook families may add dedicated event types, wrapper envelopes, or event IDs. Always validate against the product specific documentation for that webhook family rather than assuming the same body shape across all products.


---

# 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://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference.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.
