Phil Leggetter Phil Leggetter

How to Secure and Verify Vapi Webhooks with Hookdeck

Published · Updated


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.

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 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 settingValue
Algorithmsha256 (or sha1, sha512)
Signature Headerx-signature (or a name you choose)
Signature Encodinghex (or base64, base64url)
Payload Format{body}
Include TimestampOff (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:

{
  "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:

{
  "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 you want at the Server URL, so you know what your endpoint receives:

{
  "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:

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 verifies the credential's signature at the source URL, using the same settings you chose in Vapi.

  1. Create a free Hookdeck account.
  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.

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. 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, 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 and continue with how to test and replay Vapi webhooks locally. For more background, see the guide to Vapi webhooks.


Phil Leggetter

Phil Leggetter

Head of Developer and Agentic Experiences

Phil is Head of Developer and Agentic Experiences at Hookdeck with expertise in real-time communications technologies, and creator of the AAARRRP Developer Relations strategy framework.