> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casefile.win/llms.txt
> Use this file to discover all available pages before exploring further.

# Check a webhook's signature

> Make sure a webhook request came from Casefile before you act on it.

Casefile signs every webhook request with your endpoint's secret, as the [Standard Webhooks specification](https://www.standardwebhooks.com/) describes.
Check the signature before you act on a request, so no one else can pass as Casefile.

## Before you start

* Your endpoint's signing secret, which starts with `whsec_`.
  In Casefile, open the organization menu, then Settings, then Webhooks, choose the endpoint, and choose Show beside Signing secret.
* A receiver that can read a request's body exactly as it arrived.

## Steps

**1. Keep the body as it arrived**

Read the body as text before you parse it as JSON.
The signature covers the exact text, so a body parsed and written out again no longer matches it.

**2. Read the three headers**

Each request carries `webhook-id`, `webhook-timestamp` and `webhook-signature`.

**3. Check the signature**

Pass the secret, the headers and the body to this function.
It returns the event's ID when the request came from Casefile, and undefined when it did not or when it was sent too long ago.

```javascript verify-webhook.mjs theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto'

// How far a request's time may be from your clock, so an old request cannot be sent again.
const TOLERANCE_SECONDS = 5 * 60

/**
 * Checks that a request came from Casefile. `headers` are the request's
 * headers with lowercase names, and `body` is its body exactly as it arrived,
 * before any JSON parsing. Returns the event's ID, or undefined when the
 * request is not from Casefile.
 */
export const verifyWebhook = (secret, headers, body, now = Date.now()) => {
  const id = headers['webhook-id']
  const timestamp = headers['webhook-timestamp']
  const signatures = headers['webhook-signature']
  if (!id || !timestamp || !signatures) return undefined
  if (Math.abs(now / 1000 - Number(timestamp)) > TOLERANCE_SECONDS)
    return undefined

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = createHmac('sha256', key)
    .update(`${id}.${timestamp}.${body}`)
    .digest()

  // During a secret's rotation the header holds one signature for each secret, separated by spaces.
  for (const signature of signatures.split(' ')) {
    const [version, value] = signature.split(',')
    if (version !== 'v1' || value === undefined) continue
    const given = Buffer.from(value, 'base64')
    if (given.length === expected.length && timingSafeEqual(given, expected))
      return id
  }
  return undefined
}
```

For 24 hours after a secret is rotated, each request carries one signature made with the old secret and one made with the new.

The function accepts a request when any of its signatures matches your secret.

**4. Skip events you have handled**

Casefile may send the same event more than once, each time with the same `webhook-id`.
Keep the IDs you have handled, and skip a request whose ID you have seen.

**5. Answer quickly**

Answer within 15 seconds with a status from `200` to `299`.
Any other answer, or none in time, counts as a failure, and Casefile sends the same event again up to 7 times over about 28 hours.

Do slow work after you answer.

> [!TIP]
>
> The function returns the event's ID for a request from Casefile, and undefined
> for the same request with one character of its body changed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.