# How to Secure and Verify Vapi Webhooks with Hookdeck

Vapi sends call events such as `status-update` and `end-of-call-report` to a Server URL you configure. A new Server URL has no authentication, so anyone who learns it can post fabricated call reports to your system. Vapi lets you attach a credential to the URL, and Event Gateway can verify that credential's signature before an event reaches your code.

This guide shows how to create a Vapi HMAC credential, verify it manually, and verify it with Event Gateway. For events and Server URL levels, see the [guide to Vapi webhooks](/webhooks/platforms/guide-to-vapi-webhooks-features-and-best-practices).

## How Vapi HMAC credentials work

Vapi doesn't define one fixed signature scheme. You create a custom credential and choose how requests are signed. The [Vapi server authentication documentation](https://docs.vapi.ai/server-url/server-authentication) lists these HMAC settings:

* **Secret Key:** the HMAC secret.
* **Algorithm:** the hash algorithm, such as `sha256` or `sha1`.
* **Signature Header:** the header that holds the signature, such as `x-signature`.
* **Include Timestamp:** whether a timestamp is part of the signed content.
* **Timestamp Header:** an optional header for replay protection.
* **Payload Format:** a template for what is signed, built from placeholders such as `{body}` and `{timestamp}`.
* **Signature Encoding:** how the digest is encoded, such as `hex`.

You then reference the credential by its `credentialId` in the `server` object of an assistant, phone number, or tool.

## Create the Vapi HMAC credential

In the Vapi dashboard, open **Integrations**, then **Server Configuration**, and select **Add Custom Credential**. Set **Authentication Type** to **HMAC**, name the credential, and enter a secret.

Match these settings to what the Vapi source in Event Gateway verifies:

| Vapi setting | Value |
| --- | --- |
| Algorithm | `sha256` (or `sha1`, `sha512`) |
| Signature Header | `x-signature` (or a name you choose) |
| Signature Encoding | `hex` (or `base64`, `base64url`) |
| Payload Format | `{body}` |
| Include Timestamp | Off (`includeTimestamp: false` in the API) |

The Event Gateway Vapi source computes the HMAC over the raw request body, and `{body}` with the timestamp turned off tells Vapi to sign exactly that. With these settings, each request has an `x-signature` header holding the 64-character lowercase hex digest of the body. Through the API, the credential looks like this:

```json
{
  "provider": "custom-credential",
  "name": "hookdeck-hmac",
  "authenticationPlan": {
    "type": "hmac",
    "secretKey": "<your secret>",
    "algorithm": "sha256",
    "signatureHeader": "x-signature",
    "signatureEncoding": "hex",
    "includeTimestamp": false,
    "payloadFormat": "{body}"
  }
}

```

Attach the credential where you configure the Server URL. In the dashboard, the assistant's Server URL is under its **Advanced** tab in **Webhook Server**. Through the API, put the URL and credential in the `server` object:

```json
{
  "server": {
    "url": "https://hkdk.events/your-source-id",
    "credentialId": "cred_hmac_456"
  }
}

```

Vapi attaches the credential only when the Server URL comes from your saved configuration, such as an assistant, phone number, or tool. If a request supplies the Server URL itself, for example a transient assistant in `POST /call`, Vapi sends the webhook without the credential and verification fails.

## Choose which messages Vapi sends

Set `serverMessages` on the assistant to the list of [server messages](https://docs.vapi.ai/server-url/events) you want at the Server URL, so you know what your endpoint receives:

```json
{
  "serverMessages": ["status-update", "end-of-call-report", "tool-calls"]
}

```

A call with those three and one tool call produces four webhooks: a `status-update` when the call starts, a `tool-calls` message, a `status-update` when it ends, and an `end-of-call-report` a second or two after hang-up. Adding `transcript` or `conversation-update` sends a message for each turn of the conversation instead.

In a pair of test calls (about 43 and 100 seconds), the delivered bodies were about 5.5 KB for the first `status-update`, 8.5 KB for `tool-calls`, 10 to 18 KB for the ending `status-update`, and 23 to 39 KB for `end-of-call-report`. The last two grow with the length of the call because they include the call's messages and recording URLs.

## How to verify Vapi HMAC signatures manually

With a body-only payload format, verification is a raw-body HMAC and a constant-time comparison:

```javascript
const crypto = require("crypto");
const express = require("express");

const app = express();

app.post(
  "/webhooks/vapi",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const expected = crypto
      .createHmac("sha256", process.env.VAPI_HMAC_SECRET)
      .update(req.body)
      .digest("hex");

    const received = Buffer.from(req.headers["x-signature"] || "");
    const computed = Buffer.from(expected);
    if (
      received.length !== computed.length ||
      !crypto.timingSafeEqual(received, computed)
    ) {
      return res.sendStatus(401);
    }

    res.sendStatus(200);
    const { message } = JSON.parse(req.body);
    console.log(message.type);
  }
);

app.listen(3000);

```

Vapi's event type is nested at `message.type`, not at the top level of the body.

## How to verify Vapi webhooks with Hookdeck

[Hookdeck Event Gateway](/event-gateway) verifies the credential's signature at the source URL, using the same settings you chose in Vapi.

1. Create a [free Hookdeck account](https://dashboard.hookdeck.com/signup).
2. In the Hookdeck dashboard, create a new source and pick **Vapi** as the source type.
3. Paste the credential's secret into **Webhook Signing Secret**.
4. Under the verification settings, set the **Algorithm**, **Encoding**, and **Signature Header Key** to match the credential. Event Gateway defaults to `sha256`, `hex`, and `x-signature`.
5. Create a connection from the source to a destination, such as your application's webhook URL.
6. Set the Hookdeck source URL as the Server URL in Vapi, with the credential attached.
7. Make a test call. With the `serverMessages` above, Vapi sends a `status-update` when the call starts and ends and an `end-of-call-report` after it ends.

Valid deliveries become events and are forwarded to your destination. A delivery that fails verification gets a `401` response from Event Gateway, and the request is recorded as rejected with the cause `VERIFICATION_FAILED`, with no event created.

The usual cause is a mismatch in secret, algorithm, encoding, header name, or payload format. After you correct the source settings, you can [retry the rejected request](/docs/requests).

For a working example that creates the credential, the sources and the assistants with a script, and proves both outcomes, see the [Vapi agency routing demo](https://github.com/hookdeck/hookdeck-demos/tree/main/vapi/agency-routing). Its `npm run probe` command sends one correctly signed request (`200`, verified) and one badly signed request (`401`, rejected) to each source.

## Trim system prompts from payloads

The Vapi source type has an option to **Automatically trim system prompts from payload**. When enabled, Event Gateway removes the assistant's system prompt messages from incoming payloads after the signature has been verified, and never modifies requests that fail verification.

This keeps prompts that can contain internal instructions out of your stored events and your destination. In the demo, the option shrank a 40,161-byte `end-of-call-report` to 37,003 bytes (about 8%), because the system prompt is the only content removed. The saving grows with the length of the prompt.

## Verify that requests to your app come from Hookdeck

Verification at the source URL covers requests arriving at Event Gateway. To cover the request from Hookdeck to your application, enable [Hookdeck webhook signature verification](/docs/authentication#hookdeck-webhook-signature-verification), so your application can confirm that each request came from Hookdeck.

## Conclusion

Vapi webhooks are unauthenticated until you attach a credential. Create an HMAC credential with `payloadFormat: "{body}"` and `includeTimestamp: false`, configure the matching Vapi source in Event Gateway once, and forward only verified events.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) and continue with [how to test and replay Vapi webhooks locally](/webhooks/platforms/how-to-test-and-replay-vapi-webhooks-locally-with-hookdeck). For more background, see the [guide to Vapi webhooks](/webhooks/platforms/guide-to-vapi-webhooks-features-and-best-practices).