Disclosure: I'm Nabeel, founder of VoiceDash, a client portal for voice AI agencies. This is a lightly adapted republish of a guide from the VoiceDash blog; the canonical link points there.
TL;DR: Receiving a Retell AI webhook is easy. Running one endpoint that serves ten client agents is where agencies get hurt: you need to know which client a call belongs to, verify that the request really came from Retell, answer inside Retell's 10 second window, survive retries without double texting a customer, and log enough to answer "why didn't my CRM update?" in minutes. Below is the setup I use for every client agent, with the parts of Retell's docs that matter.
If you have only ever pasted a webhook URL into the Retell dashboard and moved on, that works for one client. At ten clients it becomes the place where silent failures hide.
What Retell sends and when
Retell POSTs a JSON body with an event and a call object to your URL as a call moves through its life. By default a voice agent sends three events:
-
call_started: the call connected. Useful for live dashboards and "call in progress" alerts, rarely needed for automation. It does not fire at all when the call never connects (for exampledial_failed,dial_no_answer,dial_busy). -
call_ended: the call is over. You get the call object (transcript, timing, disconnection reason, numbers) but notcall_analysis. -
call_analyzed: post-call analysis is finished. This one carries the full call plus thecall_analysisobject: summary, sentiment, success flag and any custom fields you defined.
There are more opt-in events (transcript_updated, and transfer_started, transfer_bridged, transfer_cancelled, transfer_ended for transfers), and you can choose per agent which events get delivered with the agent's webhook_events field. The full table is in Retell's webhooks overview. Build against a payload you actually captured, not one you remember.
If your analysis fields are not set up yet, do that first, because the quality of every call_analyzed event depends on those field definitions. I wrote up the fields I use in Retell AI Post-Call Analysis: The Fields I Set Up on Every Client Agent.
Why I automate off call_analyzed, not call_ended
call_ended arrives first, but it has no structured data. If a workflow creates a CRM contact on call_ended and then updates it on call_analyzed, you have two writes, two chances to fail, and a race between them. For most client automations I ignore call_ended and run everything from call_analyzed: upsert the contact, tag the outcome, send the follow-up text, notify the owner.
The exception is anything that must happen the moment the caller hangs up and does not need analysis, like releasing a held calendar slot. That can run on call_ended.
One more reason to subscribe to the transfer events if your agents transfer: for calls that stay connected through Retell after a transfer, telephony charges can keep running after call_analyzed arrives, and transfer_ended is where the updated call_cost shows up. If you rebill minutes, that matters.
Account-level vs agent-level webhook URLs
Retell lets you set a webhook URL for the whole account in the dashboard, and override it per agent with webhook_url on the agent. When an agent has its own URL, its events go there instead of to the account URL. That gives agencies two workable patterns.
Pattern 1: one URL per client agent
Each client's agent points at its own endpoint, for example a separate n8n workflow per client. The client is implied by the URL, so routing is trivial and a broken workflow only affects one client.
The cost is drift. Ten workflows that started as copies slowly become ten different workflows, and a fix you make in one never reaches the other nine.
Pattern 2: one shared endpoint that routes
Every agent points at one endpoint. It reads call.agent_id from the payload, looks up which client owns that agent, and hands the event to that client's config.
This is what I use once an agency passes a handful of clients: one place to verify signatures, one place to log, one place to fix bugs. Per-client differences live in a config table (which CRM, which calendar, which number to alert) instead of in copied workflows.
Whichever you choose, keep a written map of agent ID to client. You need it for routing, for billing, and for the day a client asks you to hand everything over.
Verify every request
Your webhook URL is a public endpoint that writes to client CRMs and sends texts to their customers. Anyone who finds it can post a fake call to it.
Per Retell's webhook security docs, every request carries an X-Retell-Signature header in the form v={timestamp},d={hex_digest}, where the digest is an HMAC-SHA256 of the raw body concatenated with the timestamp, keyed with your API key. The SDKs ship a verify helper. Details that trip people up:
- Verify the raw body. Many frameworks parse JSON before your handler runs. Re-serializing can change whitespace or key order and the check fails.
- Use the right key. Only the API key with the webhook badge in the dashboard verifies webhooks. If clients sit on different Retell accounts, each account signs with its own key, so a shared endpoint has to know which key to try.
- Reject stale timestamps. Retell's docs recommend refusing anything more than 5 minutes old, which blocks simple replays.
-
Optionally allowlist the source IP. Retell publishes
100.20.5.228for this.
On a no-code tool where signature checks are awkward, at minimum keep the URL unguessable and treat it like a password. Then move verification into code as soon as you can.
Answer fast, do the work later
Retell's spec is explicit: the webhook times out after 10 seconds, and if no 2xx comes back in that time it is retried up to 3 times. Events are sent in order but not blocking, so a failed call_started does not stop call_ended from arriving.
So the same event can arrive more than once, and a slow handler makes that likely. The safe pattern:
- Receive the request.
- Verify the signature.
- Store the raw event, or push it onto a queue.
- Return a 2xx immediately.
- Process the event in a separate step.
The mistake I see most is doing everything inline: look up the contact in the CRM, add a note, book something, send an SMS, and only then respond. One slow CRM call and Retell retries, and the caller gets two follow-up texts.
Here is the shape of a shared endpoint in Node with Express. It verifies, records the event once, acknowledges, and leaves processing to a worker:
import express from "express";
import { Retell } from "retell-sdk";
import { db, queue } from "./infra.js"; // your Postgres client and job queue
const app = express();
app.post(
"/retell/webhook",
express.raw({ type: "application/json" }), // keep the raw body for the signature
async (req, res) => {
const raw = req.body.toString("utf-8");
const sig = req.headers["x-retell-signature"];
const ok =
typeof sig === "string" &&
(await Retell.verify(raw, process.env.RETELL_WEBHOOK_KEY, sig));
if (!ok) return res.status(401).end();
const { event, call } = JSON.parse(raw);
const client = await db.oneOrNone(
"select id from clients where $1 = any(agent_ids)",
[call.agent_id]
);
// Idempotency: one row per call_id + event. A retry hits the conflict and stops here.
const inserted = await db.oneOrNone(
`insert into webhook_events (call_id, event, agent_id, client_id, payload)
values ($1, $2, $3, $4, $5)
on conflict (call_id, event) do nothing
returning id`,
[call.call_id, event, call.agent_id, client?.id ?? null, raw]
);
if (inserted) await queue.add("process-retell-event", { id: inserted.id });
res.status(204).end(); // acknowledge well inside the 10 second window
}
);
An unknown agent_id is stored with a null client rather than dropped, so a newly created agent that nobody mapped yet shows up in your logs instead of vanishing.
Make processing idempotent
Retries and duplicates are normal, so design for them. Every call has a unique call_id. Before acting on an event, check whether you already processed that call_id and event type; if yes, return success and do nothing.
-
A processed-events table keyed on
call_idplus event type, as above. Insert first, process second, skip on conflict. - Upserts, not inserts, in the CRM, matched on phone number or an external ID field, so a second run updates the same contact instead of creating a duplicate.
- Guard the side effects you cannot undo. A duplicate CRM note is annoying. A duplicate SMS to a customer or a double booked appointment is a client complaint. Record "sms_sent" against the call before or atomically with sending, not after.
Log enough to debug a client complaint
Sooner or later a client says "a lead called yesterday and nothing showed up in my CRM." You want to answer that in minutes, not by scrolling through workflow executions.
For every event, log: received time, event type, call_id, agent_id, the client it routed to, whether the signature passed, and the processing result with any error. Keep the raw payload for a reasonable window so you can replay an event after fixing a bug. With the table above you already have most of it; add processed_at and error columns and the complaint becomes one query:
select received_at, event, client_id, processed_at, error
from webhook_events
where call_id = $1
order by received_at;
Did Retell send it, did it verify, did processing succeed, and if not, what failed. A daily check for rows with an error, or with no processed_at after a few minutes, catches most problems before the client does.
Test webhooks before a client goes live
Webhook bugs rarely show up on the first test call. They show up on the call that is slightly different. Before launch I run at least these:
- A normal completed call that should create a contact and trigger follow-up.
- A call that hits voicemail, to confirm the voicemail branch does not text a customer as if they had spoken to the agent.
- A caller who hangs up within a few seconds, which produces sparse analysis fields that break workflows expecting values.
- An outbound call that never connects, which sends
call_endedandcall_analyzedwith nocall_started. Make sure nothing waits for a start event that will never come. - A transferred call, if the agent can transfer, so the outcome is tagged correctly.
- A replayed event: send the same payload twice and prove the idempotency guard works.
- A forged request with a bad signature, to prove it gets a 401.
Webhooks vs mid-call functions
These get mixed up. Webhooks are after the fact: nobody is waiting, so you can take your time. Mid-call custom functions are the agent calling your endpoint during the conversation to check a calendar or look up a customer, while the caller waits in silence.
They want different designs. Webhooks favor reliability: queue, retry, log. Functions favor speed: one fast lookup and a small response. Do not route a mid-call function through the same queue-and-process-later path, and do not put slow CRM writes in a function the caller is waiting on.
The bottom line
Retell AI webhooks are simple to receive and easy to get wrong at agency scale. Run client automations off call_analyzed; pick either one URL per agent or one shared routing endpoint and keep an agent-to-client map; verify every signature against the raw body with the webhook key; return a 2xx well inside 10 seconds and do the work afterwards; make processing idempotent on call_id; and log every event so client complaints become a lookup. Then test the odd calls, not just the happy path.
Retell behaviour (event list, 10 second timeout, 3 retries, signature format) checked against Retell's docs on 2026-11-14.
Drafted with AI assistance and fact-checked against each vendor's docs.
Top comments (0)