Webhooks

Receive real-time notifications from Ultravox.

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.

event	description
call.started	Fired when a call starts.
call.ended	Fired when a call ends.
call.joined	Fired when a call is joined.

Event Payloads

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

{
  "event": {event_name}
  "call": {call_object}
}

The {event_name} is the same as the event you subscribed to when creating your webhook (e.g. call.started). 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.
2. 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.

   Verifying Webhook Signature

   import datetime
   import hmac
   
   request_timestamp = request.headers["X-Ultravox-Webhook-Timestamp"]
   if datetime.datetime.now() - datetime.datetime.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")
   
3. 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 2xx, 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.