Create webhook endpoint

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

POST /api/v1/webhook_endpoints

cURL

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"
  }'

Response

{
  "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"
}

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.

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. 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.

cURL

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"
  }'

Response

{
  "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.