---
title: "Set your webhook URL"
method: POST
path: "/api/v1/webhook"
---

# Set your webhook URL

`POST /api/v1/webhook`

## Request

- Base URL: `https://ableandagent.com`
- URL: `https://ableandagent.com/api/v1/webhook`
- Auth: HTTP bearer

Every event from now on is POSTed here, signed with the secret this answers once. Setting it again replaces the URL and the secret; deliveries still waiting for the old one stop, and are in GET /api/v1/events.

## Request body

- NewWebhook
  - `url` string, required: https, at a public address — never localhost or a private network. The name is resolved again as each event is sent, and a name that resolves to a private address is not sent to: that delivery fails and is retried like any other.

## Response `201`

Set: the URL and its secret, shown this once.

- WebhookSet
  - `url` string, required
  - `secret` string, required: Signs every delivery. Shown once: keep it; setting the URL again makes a new one.
  - `createdAt` string, date-time, required: When it was set. RFC 3339 in UTC.

## Other responses

- `400`: The body is not JSON or has no url, or the URL is refused: not https, or not a public address. Codes: INVALID_JSON, INVALID, INVALID_URL.
- `401`: No key, or not a live one. Codes: UNAUTHORIZED.
- `413`: The body is larger than 65,536 bytes. Codes: PAYLOAD_TOO_LARGE.
- `415`: The body was not sent as application/json. Codes: UNSUPPORTED_MEDIA_TYPE.
- `429`: Too many requests for this key, or for this address without a key. Retry-After says how many seconds to wait. Codes: RATE_LIMITED.

---

[API](https://skmtc.dev/ableandagent/apis/able-and-agent-api.md) · [All operations](https://skmtc.dev/ableandagent/apis/able-and-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ableandagent/apis/able-and-agent-api/revisions/3bbf88fbc177?raw)