Webhooks

Setting server URLs

Learn about where you can set server URLs to handle call events.
Server URLs can be set at multiple levels in Vapi.

Server URLs can be set in multiple places in Vapi. Each level has a different priority.

The server URL with the highest priority for a relevant event will be the one that Vapi uses to send the event to.

Server URLs can be set at 4 levels in Vapi:

  • Account-wide: you can set a server URL for your broader account
  • Phone Number: server URLs can be attached to phone numbers themselves
  • Assistant: assistants can be configured with a server URL
  • Custom Tool: custom tools can have their own server URL

Setting Server URLs

Here’s a breakdown of where you can set server URLs in Vapi:

If your server requires authentication, create a custom credential before configuring the server URL.

1

Open General Settings

Open the Dashboard. Select General Settings.

2

Configure the server URL

Enter your endpoint in Server URL, then set the request Timeout.

3

Choose a credential

Expand Authorization, then choose the Credential you created. If your server does not require authentication, keep No authentication selected.

4

Add HTTP headers

If your server requires additional headers, select Add Header under HTTP Headers, then enter the required header.

5

Save the server settings

Select Save.

Configure an organization-level server URL in General Settings.

If no other server URL is set, Vapi will use this one.

Phone numbers can have a server URL attached to them in the Dashboard or via the phone number API.

If your server requires authentication, create a custom credential before configuring the server URL.

1

Select a phone number

Open the Dashboard. Select Phone Numbers, then select the phone number you want to configure.

2

Configure the server URL

Under Server URL, enter your endpoint and set the request Timeout.

3

Choose a credential

Expand Authorization, then choose the Credential you created. If your server does not require authentication, keep No authentication selected.

4

Add HTTP headers

If your server requires additional headers, select Add Header under HTTP Headers, then enter the required header.

5

Save the phone number

Select Save.

Configure a server URL for a phone number.

The server URL for phone numbers can be set 3 ways:

The phone number’s server configuration includes both the URL and optional authentication:

  • phoneNumber.server.url: The webhook endpoint URL
  • phoneNumber.server.credentialId: Authentication credential ID (optional)

For secured webhooks, create Custom Credentials and reference them using credentialId.

Assistants themselves can have a server URL attached to them.

There are 2 ways this can be done:

If your server requires authentication, create a custom credential before configuring the server URL.

1

Select an assistant

Open the Dashboard. Select Assistants, then select the assistant you want to configure.

2

Open Webhook Server settings

Select the Advanced tab, then locate Webhook Server.

3

Configure the server URL

Enter your endpoint in Server URL, then set the request Timeout.

4

Choose a credential

Under Authorization, choose the Credential you created. If your server does not require authentication, keep No authentication selected.

5

Add HTTP headers

If your server requires additional headers, select Add Header under HTTP Headers, then enter the required header.

6

Publish the assistant

Select publish in the unsaved-changes message to apply the update.

Setting server URL at the assistant level.

At assistant creation (or via an update) you can set the assistant’s server configuration.

The assistant’s server configuration includes:

  • assistant.server.url: The webhook endpoint URL
  • assistant.server.credentialId: Authentication credential ID (optional)

For secured webhooks, use Custom Credentials with credentialId instead of inline authentication.

The most granular server URL can be set on a custom tool. This can be done either in the Dashboard or via code.

If your server requires authentication, create a custom credential before configuring the server URL.

1

Create a custom tool

Open the Dashboard. Select Tools, select Create Tool, then select Custom Tool.

2

Configure the server URL

Under Server Settings, enter your endpoint in Server URL, then set the request Timeout.

3

Choose a credential

Under Authorization, choose the Credential you created. If your server does not require authentication, keep No authentication selected.

4

Add HTTP headers

If your server requires additional headers, select Add Header under HTTP Headers, then enter the required header.

5

Save the custom tool

Select the Saved control at the top of the tool editor to save the configuration.

Configure server settings for a custom tool.

Function tools can be configured with server endpoints via the tools API or within assistant configurations.

The server configuration for function tools includes:

  • tool.server.url: The function endpoint URL
  • tool.server.credentialId: Authentication credential ID (optional)

You can configure function tool servers at tool creation, assistant creation, or in updates.

Use Custom Credentials to secure your function endpoints with credentialId.

URL Priority

Events are only sent/assigned to 1 server URL in the priority stack. Here’s the order of priority:

  1. Custom Tool: if a custom tool has a server URL, the tool request will be sent to that URL
  2. Assistant: assistant server URLs are the next highest priority
  3. Phone Number: if a phone number has a server URL, it will be used over the account-wide URL
  4. Account-wide: Default / “lowest” importance. It will be used if no other server URL is set.

You will most commonly set a server URL on your account, and/or on specific assistants.