> For the complete documentation index, see [llms.txt](https://docs.dapta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dapta.ai/dcal/integrations/webhooks/verify-signature.md).

# Verify the signature

Prove that a webhook request really came from dCal: recompute the HMAC-SHA256 of the raw body with your signing secret and compare it with the X-Slate-Signature header in constant time. Node.js and Py

Every delivery dCal sends carries an `X-Slate-Signature` header. Your endpoint recomputes that signature with the webhook's signing secret and rejects any request that does not match. This page shows how the signature is built and gives you code to copy for Node.js and Python.

No screenshots here: everything happens on your server.

***

## How the signature is built

| Item      | Value                                                                   |
| --------- | ----------------------------------------------------------------------- |
| Algorithm | HMAC-SHA256                                                             |
| Key       | The webhook's whole signing secret, including the `whsec_` at the start |
| Message   | The raw request body, byte for byte, exactly as received                |
| Header    | `X-Slate-Signature`                                                     |
| Format    | `sha256=` followed by the lowercase hex digest                          |

Example header:

```
X-Slate-Signature: sha256=9f2b6c1d3e4a5b6c7d8e9f0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e
```

Two things matter when you verify:

* **Use the raw body.** Compute the HMAC over the bytes you received, before any JSON parsing. A framework that parses and re-serializes JSON can change spacing or key order, and the digest no longer matches. Read the raw body, verify it, then parse it.
* **Compare in constant time.** Use your language's timing-safe comparison (`crypto.timingSafeEqual` in Node.js, `hmac.compare_digest` in Python) instead of `==`, so nobody can guess the signature one character at a time.

***

## Node.js (Express)

{% code title="server.js" overflow="wrap" lineNumbers="true" %}

```js
const crypto = require("node:crypto");
const express = require("express");

const app = express();
const SECRET = process.env.DCAL_WEBHOOK_SECRET; // the whsec_ signing secret, as dCal showed it

// Keep the body raw: verify BEFORE parsing the JSON.
app.post("/webhooks/dcal", express.raw({ type: "application/json" }), (req, res) => {
  const received = req.get("X-Slate-Signature") || "";
  const expected =
    "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");

  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
  if (!valid) return res.status(401).send("invalid signature");

  const message = JSON.parse(req.body.toString("utf8"));
  // message.event is "booking.created", "booking.rescheduled", "booking.cancelled" or "ping"
  console.log(message.event, message.data);

  res.status(200).send("ok"); // any 2xx tells dCal the delivery landed
});

app.listen(3000);
```

{% endcode %}

***

## Python (Flask)

{% code title="app.py" overflow="wrap" lineNumbers="true" %}

```python
import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["DCAL_WEBHOOK_SECRET"].encode()  # the whsec_ signing secret, as dCal showed it


@app.post("/webhooks/dcal")
def dcal_webhook():
    raw = request.get_data()  # raw bytes, before any JSON parsing
    received = request.headers.get("X-Slate-Signature", "")
    expected = "sha256=" + hmac.new(SECRET, raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(received, expected):
        abort(401)

    message = request.get_json(force=True)
    # message["event"] is "booking.created", "booking.rescheduled", "booking.cancelled" or "ping"
    print(message["event"], message["data"])

    return "ok", 200  # any 2xx tells dCal the delivery landed
```

{% endcode %}

***

## Test it with Ping

You do not need a real booking to try your code. On **API and webhooks** > **Webhooks**, click **Ping** on the webhook's row. The test message is signed with the same secret and the same scheme as a real delivery, so a verifier that accepts the ping accepts real events too. If the row then reads **Failed**, your endpoint answered with something other than a 2xx status: check whether your verifier rejected it.

***

## Good practices

* **Keep the secret on your server only.** Store it as a setting or a secret of your app, never in code you publish or in a browser.
* **Skip repeats.** The signature proves who sent a request, but it carries no timestamp, so it does not tell you when. A delivery can also arrive more than once: every attempt of one delivery carries the same `X-Slate-Delivery` header, so keep the IDs you already handled and ignore a second copy.
* **Change the secret without losing events.** dCal never shows a secret again and cannot rotate one. Add a second webhook for the same URL, let your endpoint accept both secrets for a while, then delete the old webhook and keep only the new secret.

> **⚠️ Note:** Answering `401`, or any other status that is not 2xx, counts as a failed delivery and dCal keeps trying for up to 24 hours. When you change secrets, update your server first, so real deliveries are not rejected while you switch.

## Related

* [Webhooks](https://docs.dapta.ai/dcal/integrations/webhooks.md): add a webhook and copy its signing secret.
* [Payload reference](https://docs.dapta.ai/dcal/integrations/webhooks/payload-reference.md): every field and header.
* [Security and privacy](https://docs.dapta.ai/dcal/security-and-privacy.md): how dCal stores secrets.


---

# 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.dapta.ai/dcal/integrations/webhooks/verify-signature.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.
