Create a webhook endpoint

POST

/webhook_endpoints

import { createClient, createResources } from "@morevoice/sdk";

const mv = createResources({
  client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),
});

const webhookEndpoint = await mv.webhookEndpoints.create({
  description: "CRM sync",
  enabled_events: [
    "call.ended",
    "call.analyzed",
  ],
  url: "https://hooks.example.com/webhooks",
});
console.log(webhookEndpoint);

import os
import uuid

import requests

response = requests.post(
    "https://api.morevoice.ai/v1/webhook_endpoints",
    headers={"Authorization": f"Bearer {os.environ['MOREVOICE_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "description": "CRM sync",
        "enabled_events": [
            "call.ended",
            "call.analyzed",
        ],
        "url": "https://hooks.example.com/webhooks",
    },
)
response.raise_for_status()
print(response.json())

curl -X POST https://api.morevoice.ai/v1/webhook_endpoints \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "description": "CRM sync",
  "enabled_events": [
    "call.ended",
    "call.analyzed"
  ],
  "url": "https://hooks.example.com/webhooks"
}'

Starts sending the selected events to url, signed with a new secret (whsec_…, Standard Webhooks). The response carries the secret: this is the only time it is shown (rotate it to get a new one). Live endpoints need https; private and local addresses are refused.

Try it in the API playground with a test-mode key.

Authorizations

bearerAuth

Parameters

Header Parameters

MoreVoice-Version

string

/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example

2026-11-01

Idempotency-Key

string

>= 1 characters <= 255 characters

A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.

Example

5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17

Request Body^required

application/json

object

api_version

Render payloads in this API version (default: the current one).

string

Allowed values: 2026-11-01

description

string

<= 500 characters

enabled_events

required

An event type (call.ended), a group (call.*) or "*" for every event. At least one.

Array<string>

>= 1 items <= 100 items

max_in_flight

Deliveries in flight at once (1–100, default 10).

integer

>= 1 <= 100

metadata

Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent.

object

<= 50 properties

key

additional properties

string

<= 500 characters

url

required

An https URL (http is accepted in test mode). Private and local addresses are refused.

string

>= 1 characters <= 2048 characters

Responses

201

Created

application/json

A URL that receives signed events (Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature).

object

api_version

required

The API version event payloads are rendered in. legacy: an endpoint moved from the old webhook settings, which keeps getting the previous body ({id, event, createdAt, data}).

string

campaign_id

required

Any of:

string
null

Only this campaign’s events (endpoints moved from a campaign’s own webhook), or null.

string

/^cmp_[0-9A-Za-z]+$/

created

required

An ISO-8601 timestamp in UTC.

string format: date-time

description

required

string

disabled_at

required

Any of:

string
null

An ISO-8601 timestamp in UTC.

string format: date-time

disabled_reason

required

string | null

enabled_events

required

The event types sent to this endpoint; ["*"] means every event.

Array<string>

required

A webhook endpoint ID (prefix we_).

string

/^we_[0-9A-Za-z]+$/

legacy_headers

required

Also sends the previous X-Webhook-* headers (moved endpoints, for one deprecation cycle).

boolean

livemode

required

true in live mode, false in test mode.

boolean

max_in_flight

required

Deliveries in flight to this endpoint at once; more wait their turn.

integer

>= -9007199254740991 <= 9007199254740991

metadata

required

Up to 50 key/value pairs (keys up to 40 characters, values up to 500) you attach to an object. Returned as sent.

object

<= 50 properties

key

additional properties

string

<= 500 characters

object

required

string

Allowed value: webhook_endpoint

previous_secret_expires_at

required

Any of:

string
null

An ISO-8601 timestamp in UTC.

string format: date-time

secret

The signing secret (whsec_…). Returned only when the endpoint is created and when its secret is rotated: store it then.

string

status

required

auto_disabled: every delivery failed for 72 hours, so sending stopped (and your admins were told). Set status: enabled to resume.

string

Allowed values: enabled disabled auto_disabled

updated

required

An ISO-8601 timestamp in UTC.

string format: date-time

url

required

Where events are POSTed.

string

Example

{
  "api_version": "2026-11-01",
  "campaign_id": null,
  "created": "2026-11-03T09:14:22.000Z",
  "description": "CRM sync",
  "disabled_at": null,
  "disabled_reason": null,
  "enabled_events": [
    "call.ended",
    "call.analyzed"
  ],
  "id": "we_4Gk2LmN9pQ4rS6tV8wX0yZ",
  "legacy_headers": false,
  "livemode": true,
  "max_in_flight": 10,
  "metadata": {},
  "object": "webhook_endpoint",
  "previous_secret_expires_at": null,
  "status": "enabled",
  "updated": "2026-11-03T09:14:22.000Z",
  "url": "https://hooks.example.com/webhooks"
}

400

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

401

No valid API key was sent.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

403

The key may not do this (a missing scope, a plan limit, or a compliance block).

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

409

The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "idempotency_mismatch",
    "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch",
    "message": "This Idempotency-Key was already used with different parameters.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "idempotency_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

429

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying.

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

500

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

Create a webhook endpoint

Authorizations

Parameters

Header Parameters

Example

Example

Request Bodyrequired

Responses

201

Example

400

Example

Headers

401

Example

Headers

403

Example

Headers

409

Example

Headers

429

Example

Headers

500

Example

Headers

Request Body^required