How to Secure and Verify Retell AI Webhooks with Hookdeck
Retell AI sends call_started, call_ended, and call_analyzed webhooks to a URL you configure. If your endpoint doesn't check the signature, anyone who finds the URL can post a fabricated call_analyzed event and have your system store a transcript or trigger a follow-up for a call that never happened.
This guide covers how Retell signs webhooks, how to verify them yourself, and how to have Event Gateway verify them before they reach your application. For events, retries, and configuration, see the guide to Retell AI webhooks.
How Retell signs webhooks
The Retell secure webhook documentation describes the scheme. Each request has an X-Retell-Signature header in the form v={timestamp},d={hex_, where v is a Unix timestamp in milliseconds and d is an HMAC-SHA256 hex digest of the raw request body with the timestamp appended.
Two details to get right:
- The secret is a Retell API key. Retell has no separate webhook secret. Retell signs with the API key that shows a webhook badge in the dashboard, and other keys fail verification.
- The timestamp is appended to the body. The signed message is
raw_body + timestamp, with no separator.
To choose the webhook key, open Settings, then API Keys, and select Set as Webhook Key (manage API keys). Only one key can be the webhook key at a time.
How to verify Retell webhooks manually
The Retell SDKs include a verify helper. Pass it the raw body, because re-serializing parsed JSON can change whitespace or key order and break the signature:
import express from "express";
import { Retell } from "retell-sdk";
const app = express();
app.post(
"/webhooks/retell",
express.raw({ type: "application/json" }),
async (req, res) => {
const valid = await Retell.verify(
req.body.toString("utf8"),
process.env.RETELL_API_KEY,
req.headers["x-retell-signature"]
);
if (!valid) return res.sendStatus(401);
res.sendStatus(200);
const { event, call } = JSON.parse(req.body);
console.log(event, call.call_id);
}
);
app.listen(3000);
Retell.verify is async and takes the raw body, the API key, and the signature header, in that order. Retell also recommends rejecting requests whose timestamp is more than five minutes from the current time.
Every service that receives Retell events then holds your API key and the verification code. Because the signing secret is your API key, a leak in one of those services exposes more than webhooks.
How to verify Retell webhooks with Hookdeck
Hookdeck Event Gateway verifies X-Retell-Signature at the source URL, so the API key is stored in one place and your handlers receive only verified events.
- Create a free Hookdeck account.
- In the Hookdeck dashboard, create a new source and pick Retell as the source type.
- Paste the Retell API key that has the webhook badge (the key set as the webhook key) into Webhook Signing Secret.
- Create a connection from the source to a destination, such as your application's webhook URL.
- Copy the source URL Hookdeck gives you.
- In the Retell dashboard, enter that URL in the Webhooks tab for account-level events. To send one agent's events to Hookdeck instead, set the agent's
webhook_urlto the Hookdeck source URL. - Make a test call. Retell sends
call_started,call_ended, andcall_analyzedby default. A call that never connects, such as a failed dial, sends onlycall_endedandcall_analyzed.
In the Hookdeck dashboard, each valid delivery becomes an event and is forwarded to your destination. A delivery that fails verification is recorded as a rejected request with the cause VERIFICATION_FAILED, which most often means the wrong API key was pasted. See requests for how rejected requests are retried after you correct the secret.
What Event Gateway verifies
Event Gateway parses v and d from the header, recomputes HMAC-SHA256 over the raw body followed by the timestamp using your API key, and compares the digests in constant time.
Deduplicate retried events
Retell retries up to three times when it doesn't get a 2xx within 10 seconds, so the same event can arrive more than once. Deduplicate on the event type and call.call_id, and make your handler idempotent.
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 and not from someone who found your destination URL.
Conclusion
Retell signs each webhook with an HMAC keyed by your API key, over the raw body plus a timestamp. Verify it in each handler with the SDK, or configure a Retell source once in Event Gateway and forward only verified events.
Get started with Hookdeck and continue with how to test and replay Retell AI webhooks locally. For more background, see the guide to Retell AI webhooks.