Register a Retell webhook to receive real-time call_started, call_ended, and call_analyzed events, with Node.js, Python, and signature verification code.
1
Create your server endpoint
Set up an HTTP or HTTPS endpoint function that can accept webhook requests with a POST method.Example endpoint:
// install the sdk: https://docs.retellai.com/get-started/sdkimport { Retell } from "retell-sdk";import express, { Request, Response } from "express";const app = express();app.use(express.json());app.post("/webhook", (req: Request, res: Response) => { const {event, call} = req.body; switch (event) { case "call_started": console.log("Call started event received", call.call_id); break; case "call_ended": console.log("Call ended event received", call.call_id); break; case "call_analyzed": console.log("Call analyzed event received", call.call_id); break; default: console.log("Received an unknown event:", event); } // Acknowledge the receipt of the event res.status(204).send();});
ngrok (Ctrl+C to quit)Session Status onlineAccount inconshreveable (Plan: Free)Version 3.0.0Region United States (us)Latency 78msWeb Interface http://127.0.0.1:4040Forwarding https://84c5df474.ngrok-free.dev -> http://localhost:8080
Your webhook endpoint will be https://84c5df474.ngrok-free.dev/webhook
4
Register your webhook endpoint
You have two options:Option 1: Register an account level webhook
Set up through the system settings’ webhooks tab for events related to any agent under your account.
Option 2: Register an agent level webhook
Open the agent editor and expand Webhook settings. For a conversation flow, select Global settings first. Enter your endpoint in Agent Level Webhook URL. If set, account-level webhooks will not be triggered for that agent.
Set the agent endpoint in Webhook settings.
The webhook URL field accepts dynamic variables. Type {{ to open a list of available variables, or wrap a name in double curly braces yourself (for example https://example.com/webhook?customer={{customer_name}}). Each variable is replaced with its value per call before the event is delivered.Use the Test button to send a sample request to your endpoint. If your URL uses variables whose values are only known during a live call (such as contact or CRM fields), the Test button is disabled and a tooltip explains why — the webhook will still work on real calls, but it can’t be tested here because there are no values to substitute yet. Variables that Retell can resolve ahead of time, such as system variables and your version’s environment variables, can be tested normally.
5
Verify your webhook endpoint
Start a web call in the dashboard to verify the webhook is triggered correctly.
Was this page helpful?
⌘I
Assistant
Responses are generated using AI and may contain mistakes.