---
title: "Create webhook"
method: POST
path: "/api/v1/webhooks"
tags: ["Webhooks"]
---

# Create webhook

`POST /api/v1/webhooks`

## Request

- Base URL: `https://botsee.io`
- URL: `https://botsee.io/api/v1/webhooks`
- Auth: HTTP bearer

Registers a webhook URL. Returns the webhook with its signing secret (shown only once).

## Request body

- object
  - `events` unknown[]: Events to subscribe to. Call GET /api/v1/webhooks/events for the canonical catalog of currently-emitted event types and their payload schemas.
    - unknown
  - `url` string, required: HTTPS URL to receive webhook payloads

## Response `201`

Resource created.

- object
  - `webhook` object
    - `created_at` string
    - `events` string[]
    - `failure_count` integer
    - `last_triggered_at` string, nullable
    - `secret` string
    - `status` string
    - `url` string
    - `uuid` string

## Other responses

- `401`: Missing, invalid, or revoked API key.
- `403`: Authenticated but lacks permission (e.g. botsee_disabled).
- `404`: The requested resource does not exist or is not accessible.
- `422`: Request body or parameters failed validation.
- `429`: Too many requests. Wait and retry per Retry-After header.

---

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