# Verify the signature

> How to confirm that a webhook really came from Messajo, with examples in several languages.

## Why verify

Your webhook URL is public. Without checking the signature, anyone who finds the URL can send fake events — a made-up "message received", a "payment" that never happened. The signature proves the body came from Messajo, with your secret, and was not changed on the way. The timestamp inside it stops someone from recording a delivery and replaying it later.

## The header

Every delivery carries the `Messajo-Signature` header:

```text
Messajo-Signature: t=1762697007,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

- `t` is the signing time, in Unix seconds. It appears only once.
- `v1` is the HMAC-SHA256 in hexadecimal. During [secret rotation](#rotate-the-secret-without-downtime) there are **two** `v1`, one per active secret: one match is enough.
- Ignore schemes you don't know (a future `v2=`, for example).

The destination secret starts with `whsec_` and is shown **only once**, when you create the destination (in the dashboard or in the `POST /v1/destinations` response). After that the dashboard shows only its last 4 characters. Lost it? Rotate the secret.

## Step by step

1. Read the request's **raw body**, exactly the bytes that arrived, **before** any JSON parsing.
2. Split `t` and the `v1` values out of the header.
3. Build the message `${t}.${body}` — the timestamp, a dot and the raw body.
4. Compute the HMAC-SHA256 of that message using the **whole secret** as the key, `whsec_` prefix included, in UTF-8. Output in lowercase hexadecimal.
5. Compare with each `v1` in **constant time** (`timingSafeEqual`, `hmac.compare_digest`, `hash_equals`). Comparing with `==` leaks information through response time.
6. Reject if `t` is more than **5 minutes** away from your clock, in the past or in the future.

Invalid signature → respond `400` and drop the event. Valid → respond `2xx` fast and process later (see [Events](/en/webhooks/events/#order-and-duplicates)).

## Examples

The three examples use no external library and are tested on every build against Messajo's signer.

### Node.js

<Code code={nodeSnippet} lang="ts" title="verify.ts" />

### Python

<Code code={pythonSnippet} lang="python" title="verify.py" />

### PHP

<Code code={phpSnippet} lang="php" title="verify.php" />

How to get the raw body in each framework:

| Framework | Raw body |
|---|---|
| Express | `app.post("/webhook", express.raw({ type: "application/json" }), …)` and `req.body.toString("utf8")` |
| Hono | `await c.req.text()` |
| FastAPI | `await request.body()` |
| Laravel | `$request->getContent()` |

Use the raw body for verification and only then run `JSON.parse` / `json.loads` / `json_decode`.

## n8n

1. In the **Webhook** node, under **Options**, turn on **Raw Body**.
2. After it, a **Code** node (JavaScript) with the Node.js example code, reading the `messajo-signature` header and the raw body of the incoming item.
3. The Code node only loads `crypto` if n8n allows it: set `NODE_FUNCTION_ALLOW_BUILTIN=crypto` in n8n's environment and restart it.
4. Invalid signature → stop the flow (a **Stop and Error** node or an **IF**).

## Rotate the secret without downtime

1. In the dashboard, open the destination and click **Rotate secret**, or call `POST /v1/destinations/{id}/rotate-secret`. Messajo generates a new secret and shows it only once.
2. Pick the **overlap window**: from 0 to 72 hours, **24 hours** by default (`keep_previous_hours` in the API). During the window both are valid and each delivery carries two `v1`, first the new secret's, then the old one's:

   ```text
   Messajo-Signature: t=1762697007,v1=<hmac with the new>,v1=<hmac with the old>
   ```

3. Swap the secret in your application within the window. Since one matching `v1` is enough, there is no moment when events get rejected. The end of the window shows on the destination (`previous_secret_expires_at` in the API).
4. Once the window is over, the old secret stops signing and deliveries go back to a single `v1`.

With a `0` window the old secret stops signing right away: use it only when the secret leaked. Rotating again within the window drops the older one: only the current secret and the one it just replaced stay valid.

## Common mistakes

- **Re-serialized JSON.** The framework parsed the body and you signed `JSON.stringify(req.body)`. Whitespace, key order and escaping of accents change and the HMAC no longer matches. Use the raw body.
- **Wrong clock.** A server without NTP drifts outside the 5 minutes and rejects everything as stale. Sync the clock.
- **Secret with whitespace.** A space or line break at the end of the copied secret (common in `.env`). Check its length and trim it.
- **Secret without the prefix.** The HMAC key is the whole secret, **with** `whsec_`.
- **Body decoded with another charset.** Read the bytes as UTF-8; accents and emoji matter.
