---
title: "Create a webhook; the response carries its signing secret once"
method: POST
path: "/api/v1/webhooks"
tags: ["Agents API: webhooks"]
---

# Create a webhook; the response carries its signing secret once

`POST /api/v1/webhooks`

## Request

- Base URL: `https://three.ws`
- URL: `https://three.ws/api/v1/webhooks`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `url` string, uri, required: HTTPS endpoint that receives events.
  - `events` string[]: Event types from GET /api/v1/webhooks/events. Empty means all.
  - `agentId` string, uuid: Limit the endpoint to one agent. Account events are then unavailable.
  - `description` string: Free text shown in the dashboard.

## Response `200`

The { data, meta: { requestId, timestamp } } envelope.

## Other responses

- `201`: Created. Same envelope.
- `400`: invalid_parameter, bad_json or a route-specific validation code.
- `401`: unauthorized
- `403`: insufficient_scope
- `404`: not_found
- `429`: rate_limited, with Retry-After.

---

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