# Create a webhook endpoint (/api-reference/webhooks/createWebhookEndpoint)

## POST /api/v1/webhook-endpoints/

Operation ID: `createWebhookEndpoint`
Create a webhook endpoint
Registers a URL that receives the event types in `events` (empty means all). The response carries the signing `secret` (`whsec_...`) once; store it to verify deliveries.

### Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `Idempotency-Key` | header | no | Any unique string up to 255 characters. A concurrent duplicate gets `409 idempotency_request_in_progress`. The success body holds a secret, so it is never stored: retrying a completed request with the same key returns `409 idempotency_key_reused` instead of acting twice. |

### Request body

`application/json` (required)

```json
{
  "properties": {
    "description": {
      "default": "",
      "description": "Label shown in the console.",
      "maxLength": 500,
      "title": "Description",
      "type": "string"
    },
    "enabled": {
      "default": true,
      "description": "Set false to create the endpoint without sending to it yet.",
      "title": "Enabled",
      "type": "boolean"
    },
    "events": {
      "description": "Event types to receive (see `GET /webhook-event-types`). Empty means every event type.",
      "items": {
        "type": "string"
      },
      "maxItems": 50,
      "title": "Events",
      "type": "array"
    },
    "url": {
      "description": "Public `https://` URL that receives events.",
      "maxLength": 2048,
      "minLength": 1,
      "title": "Url",
      "type": "string"
    }
  },
  "required": [
    "url"
  ],
  "title": "WebhookEndpointCreate",
  "type": "object"
}
```

Example:

```json
{
  "description": "CRM sync",
  "events": [
    "call.completed",
    "call.escalated",
    "lead.created"
  ],
  "url": "https://example.com/hooks/call-mitra"
}
```

### Responses

#### 200 OK

Example (example):

```json
{
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
  "success": true,
  "webhookEndpoint": {
    "consecutiveFailures": 0,
    "createdAt": "2026-11-01T08:15:00+00:00",
    "description": "CRM sync",
    "enabled": true,
    "events": [
      "call.completed",
      "call.escalated",
      "lead.created"
    ],
    "id": "4f0c2a8e-7b1d-4c39-9a51-2d6e8f3b1c07",
    "lastStatus": "HTTP 200",
    "lastSuccessAt": "2026-11-15T10:42:07.512000+00:00",
    "updatedAt": "2026-11-15T10:42:07.512000+00:00",
    "url": "https://example.com/hooks/call-mitra"
  }
}
```

#### 400 Bad request: `bad_request`, `webhook_event_type_unknown`, `webhook_https_required`, `webhook_url_invalid`.

Example (The request could not be processed.):

```json
{
  "detail": "The request could not be processed.",
  "error": {
    "code": "bad_request",
    "docUrl": "https://docs.callmitra.ai/errors/bad_request",
    "message": "The request could not be processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (One or more event types are not recognised.):

```json
{
  "detail": "One or more event types are not recognised.",
  "error": {
    "code": "webhook_event_type_unknown",
    "docUrl": "https://docs.callmitra.ai/errors/webhook_event_type_unknown",
    "message": "One or more event types are not recognised.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (The webhook URL must use https.):

```json
{
  "detail": "The webhook URL must use https.",
  "error": {
    "code": "webhook_https_required",
    "docUrl": "https://docs.callmitra.ai/errors/webhook_https_required",
    "message": "The webhook URL must use https.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

Example (The webhook URL is not a valid public URL.):

```json
{
  "detail": "The webhook URL is not a valid public URL.",
  "error": {
    "code": "webhook_url_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/webhook_url_invalid",
    "message": "The webhook URL is not a valid public URL.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 401 Unauthorized: `api_key_expired`, `invalid_api_key`, `unauthenticated`.

Example (The API key has expired.):

```json
{
  "detail": "The API key has expired.",
  "error": {
    "code": "api_key_expired",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_expired",
    "message": "The API key has expired.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (The API key is invalid or has been revoked.):

```json
{
  "detail": "The API key is invalid or has been revoked.",
  "error": {
    "code": "invalid_api_key",
    "docUrl": "https://docs.callmitra.ai/errors/invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

Example (Authentication required.):

```json
{
  "detail": "Authentication required.",
  "error": {
    "code": "unauthenticated",
    "docUrl": "https://docs.callmitra.ai/errors/unauthenticated",
    "message": "Authentication required.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "authentication_error"
  }
}
```

#### 403 Forbidden: `api_key_scope_denied`, `permission_denied`, `webhook_workspace_required`.

Example (The API key does not have the scope required for this request.):

```json
{
  "detail": "The API key does not have the scope required for this request.",
  "error": {
    "code": "api_key_scope_denied",
    "docUrl": "https://docs.callmitra.ai/errors/api_key_scope_denied",
    "message": "The API key does not have the scope required for this request.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (You do not have permission to perform this action.):

```json
{
  "detail": "You do not have permission to perform this action.",
  "error": {
    "code": "permission_denied",
    "docUrl": "https://docs.callmitra.ai/errors/permission_denied",
    "message": "You do not have permission to perform this action.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

Example (Webhooks are managed inside a workspace.):

```json
{
  "detail": "Webhooks are managed inside a workspace.",
  "error": {
    "code": "webhook_workspace_required",
    "docUrl": "https://docs.callmitra.ai/errors/webhook_workspace_required",
    "message": "Webhooks are managed inside a workspace.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "permission_error"
  }
}
```

#### 409 Conflict: `idempotency_key_reused`, `idempotency_request_in_progress`, `webhook_endpoint_limit_reached`.

Example (This Idempotency-Key was already used with a different request body.):

```json
{
  "detail": "This Idempotency-Key was already used with a different request body.",
  "error": {
    "code": "idempotency_key_reused",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request body.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (A request with this Idempotency-Key is still being processed.):

```json
{
  "detail": "A request with this Idempotency-Key is still being processed.",
  "error": {
    "code": "idempotency_request_in_progress",
    "docUrl": "https://docs.callmitra.ai/errors/idempotency_request_in_progress",
    "message": "A request with this Idempotency-Key is still being processed.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "idempotency_error"
  }
}
```

Example (This workspace already has the maximum number of webhook endpoints.):

```json
{
  "detail": "This workspace already has the maximum number of webhook endpoints.",
  "error": {
    "code": "webhook_endpoint_limit_reached",
    "docUrl": "https://docs.callmitra.ai/errors/webhook_endpoint_limit_reached",
    "message": "This workspace already has the maximum number of webhook endpoints.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "conflict_error"
  }
}
```

#### 422 Invalid parameters: `parameter_invalid`.

Example (One or more parameters are invalid.):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "phone"
      ],
      "msg": "Field required",
      "type": "missing"
    }
  ],
  "error": {
    "code": "parameter_invalid",
    "docUrl": "https://docs.callmitra.ai/errors/parameter_invalid",
    "message": "One or more parameters are invalid.",
    "param": "phone",
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "invalid_request_error"
  }
}
```

#### 429 Too many requests: `rate_limit_exceeded`.

Example (Too many requests. Slow down and retry later.):

```json
{
  "detail": "Too many requests. Slow down and retry later.",
  "error": {
    "code": "rate_limit_exceeded",
    "docUrl": "https://docs.callmitra.ai/errors/rate_limit_exceeded",
    "message": "Too many requests. Slow down and retry later.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "rate_limit_error"
  }
}
```

#### 500 Server error: `internal_error`.

Example (Something went wrong on our side.):

```json
{
  "detail": "Something went wrong on our side.",
  "error": {
    "code": "internal_error",
    "docUrl": "https://docs.callmitra.ai/errors/internal_error",
    "message": "Something went wrong on our side.",
    "param": null,
    "requestId": "req_5f1c2e9b7a3d4c0e8b6a1f2d3c4b5a69",
    "type": "api_error"
  }
}
```

### Error codes

- [`bad_request`](/errors/bad_request)
- [`webhook_event_type_unknown`](/errors/webhook_event_type_unknown)
- [`webhook_https_required`](/errors/webhook_https_required)
- [`webhook_url_invalid`](/errors/webhook_url_invalid)
- [`api_key_expired`](/errors/api_key_expired)
- [`invalid_api_key`](/errors/invalid_api_key)
- [`unauthenticated`](/errors/unauthenticated)
- [`api_key_scope_denied`](/errors/api_key_scope_denied)
- [`permission_denied`](/errors/permission_denied)
- [`webhook_workspace_required`](/errors/webhook_workspace_required)
- [`idempotency_key_reused`](/errors/idempotency_key_reused)
- [`idempotency_request_in_progress`](/errors/idempotency_request_in_progress)
- [`webhook_endpoint_limit_reached`](/errors/webhook_endpoint_limit_reached)
- [`parameter_invalid`](/errors/parameter_invalid)
- [`rate_limit_exceeded`](/errors/rate_limit_exceeded)
- [`internal_error`](/errors/internal_error)
