> 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/faqs-and-troubleshooting/webhooks-and-error-codes/why-is-x-webhook-signature-missing-from-some-webhook-deliveries.md).

# Why is x-webhook-signature missing from some webhook deliveries?

**Short answer:** the terminal that produced the event has no `signingSecret` configured. This happens when a terminal has only ever received `webhookUrls` deliveries and has never had a terminal level default webhook set. Deliveries in this state are sent without an `x-webhook-signature` header, silently, with no error or warning on either side.

**Why this happens**

Bead has two payment webhook delivery paths for a given terminal:

* The terminal's default webhook, set via `PUT /Terminals/{id}/webhook`
* Per payment `webhookUrls` passed on `POST /Payments` (or the deprecated `POST /Payments/crypto`)

Both paths are signed using the same terminal `signingSecret`, and that secret is only created the first time `PUT /Terminals/{id}/webhook` succeeds for that terminal. If that call has never been made for a terminal, the terminal has no secret to sign with. Per payment `webhookUrls` deliveries for that terminal will still arrive, since delivery does not depend on having a default webhook URL configured, but they will not carry an `x-webhook-signature` header.

This most commonly affects integrators who rely entirely on `webhookUrls` for routing and never call the terminal webhook endpoint at all, since nothing in that flow requires it to work.

**How to tell if this is happening to you**

* Check whether `PUT /Terminals/{id}/webhook` has ever been called successfully for the affected terminal. If it has not, this is the cause.
* Inspect an incoming delivery for the `x-webhook-signature` header. If it is absent on every delivery for a terminal, rather than only on malformed or retried ones, this is almost always the explanation.
* This is not a per event issue. It is a per terminal, all or nothing state: either the terminal has a secret and every delivery for it is signed, or it does not and none are.

**How to fix it**

Call `PUT /Terminals/{id}/webhook` once for the affected terminal to establish a `signingSecret`, even if the URL you set there is not the one you actually use for routing. The response returns the secret:

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

Store that secret securely. Once it exists, both the terminal's default webhook and every `webhookUrls` delivery for that terminal will be signed and verifiable using it. See [Webhook Management](https://developers.bead.xyz/entity-management/terminal-management/webhook-management.md) for the full request and response reference, and [Webhook Event Reference](https://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference.md) for the verification steps.

**Related pages**

* [Webhook Management](https://developers.bead.xyz/entity-management/terminal-management/webhook-management.md): setting the terminal default webhook and where the signing secret comes from
* [Webhook Event Reference](https://developers.bead.xyz/reference-guide/operational-guides/webhook-event-reference.md): signature verification steps and the shared delivery model
* [Can I send webhook events to multiple URLs?](https://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/can-i-send-webhook-events-to-multiple-urls.md): fan out behavior and the same prerequisite
* [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): full verification code example


---

# 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/faqs-and-troubleshooting/webhooks-and-error-codes/why-is-x-webhook-signature-missing-from-some-webhook-deliveries.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.
