Skip to content
Ultravox API

Webhooks

API Key Required
The Ultravox API requires an API key. For more details see Authentication.

Webhooks allow you to receive real-time notifications about events in your Ultravox account. You can configure webhooks to send HTTP POST requests to a specified URL when certain events occur.

Available Events

The following events are available and can be specified when creating or updating a webhoook.

eventdescription
call.startedFired when a call starts.
call.endedFired when a call ends.

Event Payloads

The payloads that are sent with each webhook are passed in the request body as follows:

{
  "call": {call_object}
}

The {call_object} matches what is returned from the Get Call endpoint.

Webhooks in Ultravox

When creating a webhook, you must provide a URL that will receive the webhook notification. Your service must return an acceptable HTTP status code.

HTTP Status Codes

Your service should return a 2xx status code (we recommend 204) to confirm receipt of all webhooks. Any 4xx or 5xx response will result in a retry.

Securing Webhooks

You can optionally choose to secure your webhooks with a key. When creating a webhook, a secret key is automatically generated for you or you can choose to provide your own secret. You can update or patch your webhooks to change secrets in the event of a leak or as part of regular key rotation.

Each time your server receives an incoming webhook from Ultravox here’s how you can ensure the webhook was sent by Ultravox and hasn’t been tampered with:

  1. Timestamp Verification
  • Each incoming webhook request includes a X-Ultravox-Webhook-Timestamp header with the time the webhook was sent.
  • Verify that this timestamp is recent (e.g. within the last minute) to prevent replay attacks.
  1. Signature Verification
  • Ultravox signs each webhook using HMAC-SHA256.
  • The signature is included in the X-Ultravox-Webhook-Signature header.
  • To verify the signature:
    • Concatenate the raw request body with the timestamp.
    • Create an HMAC-SHA256 hash of this concatenated string using your webhook secret as the key.
    • Compare this hash with the provided signature.
Example: Verifying Webhook Signature
import datetime
import hmac


request_timestamp = request.headers["X-Ultravox-Webhook-Timestamp"]
if datetime.datetime.now() - datetime.dateimte.fromisoformat(request_timestamp) > datetime.timedelta(minutes=1):
  raise RuntimeError("Expired message")
expected_signature = hmac.new(WEBHOOK_SECRET.encode(), request.content + request_timestamp.encode(), "sha256").hexdigest()
for signature in request.headers["X-Ultravox-Webhook-Signature"].split(","):
  if hmac.compare_digest(signature, expected_signature):
    break  # Valid signature
else:
  raise RuntimeError("Message or timestamp was tampered with")
  1. Multiple Signatures
  • The X-Ultravox-Webhook-Signature header may contain multiple signatures separated by commas.
  • This allows for key rotation without downtime.
  • Your code should check if any of the provided signatures match your computed signature.

By implementing these checks, you ensure that only authentic, recent, and unmodified webhooks from Ultravox are processed by your system. Remember to store your webhook secret securely and never expose it in client-side code or public repositories.

Retries

When a destination URL fails to respond to an incoming webhook with a 200, we will retry using a random exponential backoff strategy as follows:

  • First retry will occur approximately 30 seconds later.
  • Subsequent retries will double the retry interval. (e.g. second retry again after 1m, third retry after 2m, etc.)
  • Total of 10 retries.

If your receiving service is still down, you can use the API to retrieve information about any calls that occurred.

List Webhooks

GET /webhooks

Lists all webhooks configured for your account. Account scoped.

cursor(Optional) Pagination cursor.

Create Webhook

POST /webhooks

Creates a new webhook configuration for your account.

None

Get Webhook

GET /webhooks/{webhook_id}

Retrieves details for a specific webhook configuration.

webhookId
required		Unique identifier for the webhook to retrieve.

Update Webhook

PUT /webhooks/{webhook_id}

Updates an existing webhook configuration. Completely replaces the webhook. For partial modifications, see Patch Webhook

webhookId
required		Unique identifier for the webhook to update.

Patch Webhook

PATCH /webhooks/{webhook_id}

Updates an existing webhook configuration. Allows partial modifications to the webhook.

webhookId
required		Unique identifier for the webhook to patch.

Delete Webhook

DELETE /webhooks/{webhook_id}

Deletes an existing webhook configuration.

webhookId
required		Unique identifier for the webhook to delete.