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 three 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 → 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 that does not define its own webhook_url 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.

Agent level (per assistant)

Set webhook_url (and webhook_secret) on an assistant to receive that assistant's call events. This overrides the account-level webhook 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.

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",
      "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