Status callbacks
Status callbacks are delivered only for calls created through the REST API. Inbound calls never emit status callbacks. Use a voice URL to handle those instead.
For an API-created call, status callbacks notify your server as the call moves through its lifecycle, so you can react to a call being answered, or track its final outcome, without polling the call resource.
Configure a status callback
Set StatusCallback (the URL) and, optionally, StatusCallbackMethod (GET or POST, defaulting to POST) when you create a call. By default, only the completed event is delivered. Subscribe to additional events by repeating StatusCallbackEvent in the create-call request.
Events
A call moves through up to four lifecycle events, each with a monotonically increasing SequenceNumber:
| Event | SequenceNumber | CallStatus | Delivered by default |
|---|---|---|---|
initiated | 0 | queued | No |
ringing | 1 | ringing | No |
answered | 2 | in-progress | No |
completed | 3 | completed, busy, no-answer, canceled, or failed | Yes |
The completed event is terminal: it fires exactly once per call, and its CallStatus carries the specific outcome rather than always being completed. A call that never rings still reaches the completed event, with CallStatus set to no-answer, busy, or failed as appropriate.
Payload
Each status callback carries the standard parameters plus the following:
| Parameter | Description |
|---|---|
Timestamp | Time the status transition occurred, formatted per RFC 2822 (for example, Tue, 14 Nov 2023 22:13:20 +0000). |
CallbackSource | Always call-progress-events. |
SequenceNumber | The event's position in the call lifecycle. See the table above. |
CallDuration | Duration of the call, in seconds. Present only on the terminal completed event. |
Delivery
Status callbacks are signed the same way as any other webhook. See verify webhook signatures. If your server does not respond with a 2xx status code, PressOne retries delivery, up to 5 attempts in total. A call can reach its terminal state through more than one internal transition (for example, both legs of a hangup); PressOne collapses these into a single completed delivery rather than sending duplicates.
Respond quickly and with a 2xx status code once you have durably recorded the event. Do not perform slow work such as external API calls before responding, since a delayed response counts against the same 10-second timeout used for other webhook requests.
Receiver example
The following server logs every transition and responds immediately. It is complete and runnable.
Next steps
- Webhooks: standard parameters, transport, and signature verification.
- Quickstart: create the outbound call that triggers these events.
- API reference: the
StatusCallback,StatusCallbackMethod, andStatusCallbackEventfields on create-call.