Setting Up a Webhook for Call Statuses

Configure an account-level webhook to receive status updates for all Voice calls.

Configure the webhook

Send a request to POST https://voice.unifonic.com/v1/providers/webhook. Set basicAuthNeeded to true only if the destination URL requires HTTP Basic Authentication. Provide username and password only when it is true.

curl --location --request POST 'https://voice.unifonic.com/v1/providers/webhook' \
--header 'AppsId: XXXXXXXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--data-raw '{
  "url": "https://example.com/voice-status",
  "basicAuthNeeded": false
}'

Configuration response

{
  "status": "Webhook has been configured successfully.",
  "url": "https://example.com/voice-status",
  "basicAuthNeeded": false
}

Receive status events

Unifonic sends call-status events to the configured URL. Return a successful HTTP response after processing each event.

{
  "callId": "1c9ebf6a-dd62-4c49-b0b3-c1b1494e01f1",
  "referenceId": "order-123",
  "status": "Completed",
  "recipient": "+966XXXXXXXXX",
  "callerId": "+966XXXXXXXXX"
}

Receive recording events

When a recording is available, the event can include a recording URL. Recording URLs remain available for 72 hours.

{
  "callId": "1c9ebf6a-dd62-4c49-b0b3-c1b1494e01f1",
  "status": "Completed",
  "recordingUrl": "https://example.com/recording.wav"
}

Error response

{
  "errorCode": "InvalidRequest",
  "message": "The webhook request is invalid."
}