> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create webhook endpoint

> Subscribe a URL to event types, and get its signing secret.

Creates an endpoint and sends it a `webhook_endpoint.test` event straight away. The response holds the endpoint's signing `secret`, which is shown only once: store it now. See [Verify the signature](https://wordsmithai.mintlify.site/webhook-endpoints.md#verify-the-signature).

A user endpoint acts as you, with the API key or OAuth app that created it. It receives an event only while you can read its resource and the credential grants the event's scope. If the key is deleted or the app disconnected, the endpoint is disabled.

## Authentication

Requires an API key, or an OAuth token with `webhooks:write`. An organisation endpoint also needs `webhooks:admin`, the organisation-webhooks permission and a plan that includes organisation endpoints.

## Body parameters

**url** `string` *required*

The public `https` URL Wordsmith sends events to.

**event\_types** `string[]` *required*

The event types to receive, from [List event types](https://wordsmithai.mintlify.site/api-reference/events/list-event-types.md). A wildcard such as `task.*` covers every event of one resource.

**description** `string`

A note to tell your endpoints apart, up to 500 characters.

**audience** `string` (default: user)

`user` receives events about what you can read. `customer` receives events about work shared with the whole organisation.

## Response

Returns `201` with the endpoint and its `secret`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.wordsmith.ai/api/v1/webhook_endpoints" \
  -H "Authorization: Bearer sk-ws-api1-your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/wordsmith",
    "event_types": ["task.assigned", "task.status_changed", "review.completed"],
    "description": "Matter management sync"
  }'
```

```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "0e7b3c5a-9d21-4f86-b4a0-6c8e2f1d7a39",
  "url": "https://your-app.com/webhooks/wordsmith",
  "description": "Matter management sync",
  "event_types": [
    "task.assigned",
    "task.status_changed",
    "review.completed"
  ],
  "audience": "user",
  "status": "enabled",
  "disabled_reason": null,
  "api_version": "2026-11-01",
  "last_delivery": null,
  "created_at": "2026-11-09T10:00:00Z",
  "updated_at": "2026-11-09T10:00:00Z",
  "secret": "whsec_4f9a1c7e2b8d6a0f3e5c9b1d7a2f8e4c4f9a1c7e2b8d6a0f"
}
```

## Errors

| Status | `error_code` | When |
| - | - | - |
| 400 | `invalid_webhook_url` | The URL is not a public `https` URL. |
| 400 | `invalid_event_type` | An event type that does not exist, or a personal one on an organisation endpoint. |
| 400 | `invalid_request_body` | A missing or unknown field. |
| 403 | `forbidden` | Your role does not allow webhook endpoints of this audience. |
| 403 | `customer_webhooks_unavailable` | Your organisation's plan does not include organisation endpoints. |
| 409 | `webhook_endpoint_limit_reached` | You have 10 endpoints, or your organisation has 50. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.