VoiceLayerDocs
Dashboard

Create a webhook subscription

POST
/v1/webhooks/subscriptions

Registers an HTTPS endpoint to receive events. The response includes the signing secret — the only time you see it. Store it and use it to verify each delivery's x-voicelayer-signature header.

Requires an API key with the webhooks:manage scope.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Request Body

application/json
  1. body
url*string

Your public HTTPS endpoint.

Formaturi
eventTypes?array<>

Exact event types or a prefix with .* (message.*). Leave it empty to receive every type.

Itemsitems <= 100
Default[]
description?string

A label for you, up to 500 characters.

Lengthlength <= 500

Response Body

Created; the signing secret is returned this once

application/json
  1. response
subscription*
Example Request
curl -X POST https://api.vlayers.ai/v1/webhooks/subscriptions \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com/voicelayer/webhooks",    "eventTypes": [      "message.*",      "conversation.*"    ]  }'
Example Response
{  "subscription": {    "id": "0192f5a7-3c4d-7e5f-8a6b-7c8d9e0f1a23",    "projectId": "0192f5a1-5e6f-7a7b-8c8d-9e0f1a2b3c45",    "url": "https://example.com/voicelayer/webhooks",    "eventTypes": [      "message.*",      "conversation.*"    ],    "description": "Production receiver",    "enabled": true,    "createdByKeyId": "key_7f2a91",    "restrictTags": [],    "createdAt": "2026-10-20T15:04:05.000Z",    "updatedAt": "2026-10-20T15:04:05.000Z",    "secret": "<shown only in this response>"  }}