Server Authentication

When configuring webhooks for your assistant, you can authenticate your server endpoints using either a secret token, custom headers, or OAuth2. This ensures that only authorized requests from Vapi are processed by your server.

Credential Configuration

Credentials can be configured at multiple levels:

1. Tool Call Level: Create individual credentials for each tool call
2. Assistant Level: Set credentials directly in the assistant configuration
3. Phone Number Level: Configure credentials for specific phone numbers
4. Organization Level: Manage credentials in the API Keys page

The order of precedence is:

1. Tool call-level credentials
2. Assistant-level credentials
3. Phone number-level credentials
4. Organization-level credentials from the API Keys page

Authentication Methods

Secret Token Authentication

The simplest way to authenticate webhook requests is using a secret token. Vapi will include this token in the X-Vapi-Signature header of each request.

Configuration

1
{
2
  "server": {
3
    "url": "https://your-server.com/webhook",
4
    "secret": "your-secret-token"
5
  }
6
}

Custom Headers Authentication

For more complex authentication scenarios, you can configure custom headers that Vapi will include with each webhook request.

This could include short lived JWTs/API Keys passed along via the Authorization header, or any other header that your server checks for.

Configuration

1
{
2
  "server": {
3
    "url": "https://your-server.com/webhook",
4
    "headers": {
5
      "Authorization": "Bearer your-api-key",
6
      "Custom-Header": "custom-value"
7
    }
8
  }
9
}

OAuth2 Authentication

For OAuth2-protected webhook endpoints, you can configure OAuth2 credentials that Vapi will use to obtain and refresh access tokens.

Configuration

1
{
2
  "server": {
3
    "url": "https://your-server.com/webhook"
4
  },
5
  "credentials": {
6
    "webhook": {
7
      "type": "oauth2",
8
      "clientId": "your-client-id",
9
      "clientSecret": "your-client-secret",
10
      "tokenUrl": "https://your-server.com/oauth/token",
11
      "scope": "optional, only needed to specify which scopes to request access for"
12
    }
13
  }
14
}

OAuth2 Flow

1. Vapi makes a request to your token endpoint with client credentials
2. Your server validates the credentials and returns an access token
3. Vapi includes the access token in the Authorization header for webhook requests
4. Your server validates the access token before processing the webhook
5. When the token expires, Vapi automatically requests a new one

OAuth2 Token Response Format

Your server should return a JSON response with the following format:

1
{
2
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3
  "token_type": "Bearer",
4
  "expires_in": 3600,
5
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",  // Optional
6
  "scope": "read write"  // Optional, only if scope was requested
7
}

Example error response:

1
{
2
  "error": "invalid_client",
3
  "error_description": "Invalid client credentials"
4
}

Common error types:

• invalid_client: Invalid client credentials
• invalid_grant: Invalid or expired refresh token
• invalid_scope: Invalid scope requested
• unauthorized_client: Client not authorized for this grant type