Webhooks Overview

Webhooks allow you to receive real-time notifications about call events. When events occur, HMS Sovereign sends HTTP POST requests to your configured endpoint.

Available Webhooks

Where webhooks are configured

Webhook (server) URLs can be set at multiple levels. A more specific level overrides a less specific one, so you can route different traffic to different backends.

Precedence: tool url → assistant webhook_url → phone number → account webhook.

Account level (organization default)

Set a webhook URL on your account in the dashboard settings. This is the organization-wide default endpoint: any assistant or number that does not define its own webhook falls back to this account-level webhook. It also receives the assistant-request event for inbound calls to phone numbers that are not linked to a specific assistant, so you can return the configuration to use for that call.

Phone number level

Set a webhook on an individual number from the dashboard: open the number under Phone numbers and fill in the Webhooks section — the URL, an optional signing secret, and which events to send. A number's webhook is used when its assigned assistant has no webhook of its own, and takes precedence over the account webhook. It's the natural place for a webhook when a number resolves its assistant dynamically at call time (see Assistant Request).

Agent level (per assistant)

Set webhook_url (and webhook_secret) on an assistant to receive that assistant's call events. This overrides the number- and account-level webhooks for that assistant.

curl -X PATCH https://api.hmsovereign.com/api/v1/assistants/ASSISTANT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://api.example.com/webhooks/hms-sovereign",
    "webhook_secret": "your-secret-for-verification",
    "webhook_events": ["assistant-request", "tool-calls", "status-update", "end-of-call-report"]
  }'

Tool level (per function)

A custom tool can define its own url. When set, that tool's tool-calls go directly to that URL instead of the assistant's webhook_url — handy for routing individual functions straight to the right backend (for example lookup_customer to your CRM and book_appointment to your calendar) without building a central router.

Arena events

Arena sends events only for a test suite that has a routine. They do not follow the precedence above: they go to the webhook_url of the routine, or else to the account webhook, and only to an https URL. Their body has the same message envelope with message.id, message.type, message.timestamp and message.arena, and they are signed with the webhook secret of your organization. See Arena: events for the payloads, the signature and the retries.

Request Format

All webhooks send POST requests with:

Headers

Body Structure

{
  "message": {
    "type": "status-update",
    "timestamp": "2025-12-13T12:00:00.000Z",
    "call": {
      "id": "5c4d030f-43e3-4e65-899e-8148521e660f",
      "type": "inbound_phone_call",
      "channel": "phone",
      "status": "in-progress"
    },
    "phone_number": {
      "number": "+31850835037",
      "name": "HMS Sovereign Demo"
    },
    "customer": {
      "number": "+31612345678"
    }
  }
}

Response Requirements

Next Steps

• Assistant Request Webhook - Dynamic assistant configuration
• Tool Calls Webhook - Function execution
• Security - Verify webhook signatures