> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/triggers-and-webhooks/webhook-secrets-and-signature-verification.md).

# Webhook Secrets and Signature Verification

Webhook verification helps confirm that an incoming event came from the expected sender. Configure the signature settings to match that sender’s documented scheme.

![Verify the original bytes before parsing](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F27yH5irra0iQw3UG2wUR%2Fwebhook-secrets-and-signature-verification.png?alt=media)

Illustrative receiver logic; helper names are not a StackAI SDK. Use the sender’s exact signing scheme, header names, encoding, and timestamp rules. Do not parse and reserialize the body before verification.

<details>

<summary>Copy the example</summary>

```python
raw_body = request.body_bytes

# Use the sender's official verification implementation.
verified_event = sender_verifier.verify(
    raw_body=raw_body,
    headers=request.headers,
    secret=secret_store.webhook_signing_secret,
)

# Only accept/process the event after verification succeeds.
process_verified_event(verified_event)
```

</details>

## Before you begin

A sender that supports signing and access to the trigger’s verification settings.

## Key concepts

| Term           | Definition                                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| HMAC signature | A message-authentication value calculated using a shared secret and payload. The receiver must use the same algorithm, encoding, and exact payload representation. |
| Raw body       | The original request bytes before parsing or reformatting. Signature verification can fail if the body is changed before verification.                             |
| Header         | A named value sent as HTTP request or response metadata. Authentication and signatures belong in the headers specified by the contract.                            |
| Secret         | Sensitive configuration such as a credential. Use supported secret fields and avoid exposing values in prompts, logs, or screenshots.                              |
| Webhook        | An HTTP request sent by one system to notify another about an event. Delivery and workflow completion are separate outcomes.                                       |

## Verify incoming webhook requests

1. Set the shared secret through the supported secret field.
2. Match the signature header and encoding to the sender’s configuration.
3. Send a signed event and inspect the result. Confirm that an invalid signature is rejected.

Valid signed events can start the workflow while invalid signatures are rejected.

## Behavior and limitations

HMAC verification depends on the exact payload bytes, shared secret, and encoding. Do not substitute an unrelated API key for a signing secret. Signature headers and hex or base64 encoding vary by provider. Keep the secret out of logs and rotate it in both systems when replacing it.

## Related resources

[Trigger Activation and Execution Context](https://docs.stackai.com/technical-reference/triggers-and-webhooks/trigger-activation-and-execution-context.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.stackai.com/technical-reference/triggers-and-webhooks/webhook-secrets-and-signature-verification.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.
