Connect Retell AI to n8n: A Practical Build Guide

This guide describes a Retell-to-n8n integration pattern for an inbound appointment flow. Treat it as an implementation design to validate against the current Retell and n8n documentation and your own test calls—not as proof of a completed client build or production readiness.

Retell can handle the live voice interaction while n8n runs downstream business logic such as CRM lookups, calendar checks, and written confirmations. Keeping those responsibilities separate makes the workflow easier to test and lets you put observable error handling around side effects.

The result should be a testable design for an inbound agent that can look up a caller, check availability, attempt one booking, and recover safely when a dependency fails.

Why pair Retell AI with n8n?#

This pairing can fit when you already run n8n, need a CRM or calendar operation that is not available as a native voice-platform action, or want orchestration logic you can version and monitor separately.

A monolithic no-code voice platform is fine until you hit its edges. The moment you need a branching booking flow, a fallback when an API fails, or an integration nobody built a native node for, you're fighting the tool. n8n gives you that escape hatch on day one.

Prerequisites:

• A Retell account with at least one agent configured
• A reachable n8n instance — n8n Cloud or a self-hosted webhook URL that's publicly accessible over HTTPS
• One downstream tool wired up: Google Calendar, HubSpot, or even a Google Sheet to start

The two integration patterns you actually need#

Retell documents two relevant contracts. Keep them separate because their payloads, timing, retry behavior, and responses are not interchangeable.

Pattern A — in-call custom function. During the conversation, Retell sends a function request to your endpoint and makes the returned data available to the conversation. Use this for a live lookup or an action whose result the agent needs before it can continue the booking flow. Retell's custom-function documentation defines the request shape, signature, configurable timeout, and retry settings.

Pattern B — lifecycle webhook. Retell sends events such as call_started, call_ended, and call_analyzed to your endpoint. Its webhook documentation says the receiver should return a successful response within ten seconds. Safely accept or queue the event, acknowledge it, and then do slower downstream work. Missing that acknowledgement can trigger retries.

How to choose: if the conversation needs the result now, use a custom function. If the task reacts to a lifecycle event and the conversation does not need the result, acknowledge a webhook and process it outside the response path.

Caller ──audio──> Retell (voice loop)
                     │
                     │  Pattern A: in-call custom function
                     ├──POST args──> n8n Webhook ──> lookup/action
                     │ <──JSON response── (agent speaks it)
                     │
                     │  Pattern B: lifecycle event
                     └──POST event──> accept / queue ──> downstream work

Step 1 — Stand up the n8n webhook endpoint#

Add a Webhook node and set the method to POST. n8n exposes separate test and production URLs: its Webhook node documentation says the test URL is registered for a test execution, while the production URL is registered when the workflow is published. Use each only in its intended environment.

Do not prescribe one payload shape for both patterns. With Retell's custom-function Payload: args only setting off, the body follows its documented name, call, and args wrapper; with that setting on, the arguments are at the top level. A lifecycle webhook instead contains an event type and a call object, with additional fields for some event types. Map each contract from the current documentation and a captured test request before you activate the workflow.

Return the response required by the contract you are handling. For a custom function, use n8n's Respond to Webhook node when you need to control the response after a lookup. For a lifecycle event, return 2xx as soon as the payload has been safely accepted rather than holding the acknowledgement open for slow work.

Verify that requests came from Retell before processing them. Retell documents an X-Retell-Signature generated from the raw request body and verified with the Retell API key. Keep credentials outside exported workflow JSON. If your n8n setup cannot preserve the raw body and perform the documented verification exactly, put a small verification service in front of n8n and forward only verified requests. Do not replace the documented check with an invented shared-secret convention.

Step 2 — Wire a Retell Custom Function to n8n#

In the Retell agent, define the function with a clear name, a plain-language description, and a valid JSON Schema. Keep the required inputs narrow. For example:

{
  "type": "object",
  "properties": {
    "phone_number": {
      "type": "string",
      "description": "Caller phone number in the format expected by the downstream system."
    }
  },
  "required": ["phone_number"]
}

Point the function URL at your n8n production webhook and map the inputs according to the payload option you selected. Capture a test request and verify the actual shape before building downstream expressions.

Write the description like an instruction, not a label. Something like "Call this to check open appointment slots when the caller asks to book" tells the model when to fire it. Vague descriptions cause two failure modes: the agent never calls the function, or it calls it on every single turn and the conversation drags.

Measure function latency with real calls and record at least P50 and P95. Set an explicit timeout that is consistent with the current Retell limit and your own conversational budget, then test what the agent says when the lookup fails or times out. Optimize the measured slow path; do not apply a universal sub-second target without evidence from your environment.

Step 3 — Build a real use case: book an appointment#

Here's the flow end to end.

Look up a known caller. On the inbound lookup function, take the caller's phone_number, query your CRM or sheet, and return only the fields the conversation needs. Handle no match and multiple matches explicitly.

Check availability. When the caller asks to book, the agent calls an availability function. Inside n8n, query Google Calendar or Cal.com for free slots and return two or three options as a short list. Don't dump twenty slots — the agent has to read them aloud.

Confirm and create. The caller picks a slot, the agent calls a booking function, and n8n creates the event. Branch on the result: on success, return a confirmation; on failure (double-booked, API error), return a clear error so the agent can recover — "That slot just filled, want the next one?" — instead of freezing.

Send written proof. After booking, trigger an SMS or email from n8n so the caller has a confirmation they can look at later. People trust a booking they can see.

Step 4 — Capture transcripts and outcomes after the call#

Subscribe only to the lifecycle events your workflow needs. Retell's Get Call documentation describes the call record and configured post-call analysis fields; do not assume every account or agent produces the same fields.

Store only purpose-limited fields. Decide whether a transcript is required, obtain any necessary consent, configure Retell's PII and storage controls, restrict access, and apply an approved retention period and deletion rule. Route operational outcomes without copying the entire call record into every downstream system.

Review a permissioned sample of calls against defined failure modes before changing the prompt. Keep that review inside the same access and retention rules as the underlying call data.

Gotchas, latency, and going to production#

A few things that will bite you if you skip them:

Trap	Fix
Endpoint not active	Confirm that Retell points to the published production webhook, not an inactive test URL.
Double bookings	Use an operation-specific idempotency key, not call_id alone.
Slow responses	Measure P50/P95, set an explicit timeout, and test the spoken fallback.
Duplicate lifecycle work	Deduplicate with the event-specific key documented for that Retell event.
Excess call data	Limit fields, access, retention, and downstream copies to the approved purpose.
Surprise bills	Log every function call, watch per-minute spend, and load-test before a real number goes live.

Idempotency deserves emphasis. A booking function can be invoked again, and lifecycle webhooks can be retried. For a booking operation, use a key such as call_id + function_name + normalized appointment slot and re-check availability inside the same operation. For per-call lifecycle events, Retell currently documents event + call_id; transfer and transcript events need different handling. Follow the current event-specific guidance instead of deduplicating every delivery on call_id alone.

Wrap-up and next steps#

Two patterns carry this architecture: custom functions when the conversation needs a result, and acknowledged lifecycle webhooks for downstream event processing. Keep their contracts, timing, verification, and idempotency rules separate.

Before production, validate signature verification, timeout behavior, duplicate protection, calendar conflicts, written confirmation, human fallback, and data-retention controls with representative test calls. For a related booking design, see the AI phone-agent guide.

If you need help evaluating a Retell and n8n automation design, get in touch.

FAQ#

Do I need to self-host n8n to use it with Retell?#

No. Use n8n Cloud or a self-hosted instance with a webhook endpoint that Retell can reach over HTTPS. Choose the hosting model only after checking your data-handling, latency, operational, and cost requirements.

How fast does the n8n response need to be for a Retell custom function?#

There is no universal sub-second requirement. Measure P50 and P95 on representative calls, set an explicit timeout within the current Retell limit and your conversational budget, and test a spoken fallback for failures and timeouts.

What's the difference between a Retell custom function and a webhook?#

A custom function sends an in-call request whose result can be used by the conversation. A lifecycle webhook reports an event; safely accept it, return 2xx within the documented acknowledgement window, and do slower work downstream.

How do I stop the agent from double-booking?#

Use an operation-specific key such as call_id + function_name + normalized appointment slot, re-check the slot inside the booking operation, and return the previous result for an exact replay. For lifecycle events, use Retell's documented event-specific key rather than call_id alone.