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.
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
sha256orsha1. - 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:
{
"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.
- Create a free Hookdeck account.
- In the Hookdeck dashboard, create a new source and pick Vapi as the source type.
- Paste the credential's secret into Webhook Signing Secret.
- Under the verification settings, set the Algorithm, Encoding, and Signature Header Key to match the credential. Event Gateway defaults to
sha256,hex, andx-signature. - Create a connection from the source to a destination, such as your application's webhook URL.
- Set the Hookdeck source URL as the Server URL in Vapi, with the credential attached.
- Make a test call. With the
serverMessagesabove, Vapi sends astatus-updatewhen the call starts and ends and anend-of-call-reportafter 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.