StatusCallback reliability: expected latency, retry logic, and handling missed callbacks
Overview
When a call ends, Exotel sends an HTTP StatusCallback to your configured StatusCallback URL with the final call status and related details, including the recording URL when available.
For most calls, this callback arrives shortly after the call completes. For a small percentage of calls (typically under 1%), the callback may be missing, delayed, or incomplete. This article covers delivery behavior, retries, expected latency, and the recommended fallback.
Expected latency
StatusCallback fires when a call reaches a final state (for example, completed, failed, busy, no-answer, or canceled).
Under normal conditions, expect delivery within a few seconds to under a minute after the call ends. In practice, delivery is typically well within 45 seconds after the callback is queued.
Note: the recording URL may still be unavailable on the first callback even when the status is final. It can arrive later, once the recording is ready.
Delivery retries to your endpoint
If Exotel can't deliver the StatusCallback to your endpoint (for example, due to a timeout, a temporary 5xx, or an HTTP 429), it retries delivery:
Detail | Value |
|---|---|
Maximum delivery attempts | Up to 4 |
Timeout per attempt | 6 seconds |
Retry spacing (on timeout) | ~30 seconds → 5 minutes → 10 minutes |
Other temporary failures (5xx / 429) | Retried with a short delay (typically ~30 seconds) |
Permanent client errors (most 4xx, except 429) | Not retried |
Your endpoint should respond with a 2xx (or a 3xx redirect) within 6 seconds for the delivery to count as successful.
When StatusCallback may be missing, late, or incomplete
In rare cases, complete call details aren't available in time, due to delays in the telecom/network path or in call finalization. When this happens, you may see one or more of the following:
- StatusCallback isn't delivered.
- StatusCallback arrives with incomplete fields (for example, status or leg details are null/empty).
- The recording URL is missing or arrives later than usual.
This is expected edge-case behavior for a small fraction of calls, and doesn't usually indicate a misconfiguration on your end.
Important: The retries described above only cover delivery failures to your URL (your server being down or slow). They don't cover the rarer case where Exotel never queues a complete final callback because call details weren't available in time. For that case, use Get Call Details.
Recommended fallback: Get Call Details API
Don't rely on StatusCallback alone for 100% coverage. Use Get Call Details as the source of truth whenever a callback is missing or incomplete:
- If you don't receive a StatusCallback for a CallSid, call Get Call Details for that CallSid.
- If the status or recording URL is still empty or incomplete, retry with backoff — for example, start 1–2 minutes after the call, then retry every few minutes.
- As a practical guideline, check again around 15 minutes after the call was placed or completed. By then, most calls have a final status available.
- Stop retrying once you have a final status (completed, failed, busy, no-answer, canceled, etc.), or once you hit a maximum retry window you define (for example, 30–60 minutes).
Recommended integration pattern
- Use StatusCallback for near-real-time updates.
- Make sure your StatusCallback endpoint responds quickly (within 6 seconds) with a 2xx.
- Use Get Call Details (with retries) to reconcile missed or incomplete callbacks.
- Optionally, run a periodic reconciliation job for CallSids you initiated but never fully resolved.
Summary
Topic | Guidance |
|---|---|
Happy-path latency | Usually seconds to under a minute after call end |
Delivery retries | Up to 4 attempts, with backoff |
Per-attempt timeout | 6 seconds |
Missed/incomplete edge cases (<1%) | Use Get Call Details with retries (~15-minute practical window) |
Recording URL | May lag behind final status — poll Get Call Details if needed |