> 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/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](/entity-management/terminal-management/webhook-management.md) for the full request and response reference, and [Webhook Event Reference](/reference-guide/operational-guides/webhook-event-reference.md) for the verification steps.

**Related pages**

* [Webhook Management](/entity-management/terminal-management/webhook-management.md) — setting the terminal default webhook and where the signing secret comes from
* [Webhook Event Reference](/reference-guide/operational-guides/webhook-event-reference.md) — signature verification steps and the shared delivery model
* [Can I send webhook events to multiple URLs?](/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?](/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 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://developers.bead.xyz/faqs-and-troubleshooting/webhooks-and-error-codes/why-is-x-webhook-signature-missing-from-some-webhook-deliveries.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.