---
title: "Register a webhook endpoint"
method: POST
path: "/v1/webhook-endpoints"
tags: ["Webhooks"]
---

# Register a webhook endpoint

`POST /v1/webhook-endpoints`

## Request

- Base URL: `https://www.chatrail.dev`
- URL: `https://www.chatrail.dev/v1/webhook-endpoints`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `chatrail_session`

Returns the signing secret **exactly once**. Every delivery is signed with HMAC-SHA256 over the timestamp, a period, and the raw request body; verify it and reject stale timestamps. The URL is validated at registration and the connection pinned at delivery, so an endpoint pointing at a private address is refused. Works with an API key holding `webhooks:write`, so a deploy script can register its own endpoint; every change is audited.

## Request body

- object
  - `url` string, uri, required
  - `description` string
  - `events` string[], required
  - `connection` string

## Response `201`

Created, with the one-time signing secret.

## Other responses

- `400`: The URL is not publicly reachable over https.
- `402`: Scoping to one connection is not on this plan.

---

[API](https://skmtc.dev/chatrail/apis/chatrail-api.md) · [All operations](https://skmtc.dev/chatrail/apis/chatrail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/chatrail/apis/chatrail-api/revisions/acc5b88c6f59?raw)