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

# Create a webhook endpoint

> Register an HTTPS receiver and retrieve its signing secret once.

Register an HTTPS receiver and retrieve its signing secret once.

Use a developer access key. See [authentication, errors, and rate limits](/api-reference/authentication).

Required scopes: `webhooks:write`.

Replace the example receiver with your own deployed HTTPS endpoint. Save `secret` in the receiver’s secret store; listing will not reveal it again. Verify [webhook signatures](/api-reference/webhooks/verification) before processing. A rejected target returns `400`.

## Parameters

<ParamField body="target_url" type="string" required>
  Trimmed HTTPS URL, 1–2,048 characters. Must resolve to a public address; URL credentials and private targets are rejected.
</ParamField>

<ParamField body="description" type="string | null">
  Optional description, at most 200 trimmed characters.
</ParamField>

<ParamField body="events" type="string[]" required>
  Nonempty list of supported event names from GET /v1/webhooks/events.
</ParamField>

## Response

**201** — Returns the resource under `data`. Example IDs and values are illustrative.

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "endpoint_example",
      "targetUrl": "https://receiver.example/webhooks/kato",
      "description": null,
      "events": [
        "record.created"
      ],
      "status": "active",
      "createdAt": "2026-09-07T12:00:00.000Z",
      "updatedAt": "2026-09-07T12:00:00.000Z",
      "secret": "whsec_example_not_a_real_secret"
    }
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash Request theme={null}
  curl --fail-with-body --silent --show-error \
    "https://api.getkato.io/v1/webhooks" \
    -H "Authorization: Bearer $KATO_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "target_url": "https://receiver.example/webhooks/kato",
    "events": [
      "record.created"
    ]
  }'
  ```
</RequestExample>

This request changes workspace data. A timeout does not prove that the write failed; inspect the result before retrying.


## Related topics

- [All endpoints](/api-reference/endpoints.md)
- [Set up webhooks](/api-reference/webhooks/setup.md)
- [Delete a webhook endpoint](/api-reference/webhooks/delete.md)
- [List webhook endpoints](/api-reference/webhooks/list.md)
- [Verify and process webhooks](/api-reference/webhooks/verification.md)