Skip to content
UltimateTeam.ai Docs

Handle Retell Webhook

POST
/api/v1/webhooks/retell

Handle incoming Retell AI voice-call webhooks.

Processes call_analyzed events:

  • Verifies HMAC-SHA256 signature via x-retell-signature header.
  • Enforces Redis idempotency (48-hour window).
  • Resolves tenant from to_number (the agent’s DID).
  • Writes ContactTimeline entry (call touch with encoded metadata).
  • On successful call: stores memory crystal + quality-gates follow-up.
  • Emits OUTREACH_CALL_COMPLETED event unconditionally.
  • Emits AGENT_TASK_QUEUED when call succeeded and quality gate passes, or when escalation is flagged regardless of success.

All other event types are acknowledged with 200 immediately.

Returns: WebhookAck with received=True on success, or status="duplicate" (still 200) when the call_id was already processed inside the idempotency window.

Raises: HTTPException: 500 when RETELL_API_KEY is unset — the HMAC secret would be the empty string, whose digest anyone can compute, so the route refuses to serve rather than verify against a publicly known key; 403 when x-retell-signature is missing or does not verify; 400 when the body is not valid UTF-8 or not valid JSON; 404 when the tenant cannot be resolved from the phone number.

Authorizations

Responses

200

Successful Response

Generic webhook acknowledgement response.

Attributes: received: Always True when the webhook was accepted. status: Optional status string (e.g. “duplicate” for idempotent replay).

object
received
boolean
default: true
status
Any of:
string