---
title: "Register a webhook"
method: POST
path: "/webhooks"
---

# Register a webhook

`POST /webhooks`

## Request

- Base URL: `https://vineverse.bible/api/v1`
- URL: `https://vineverse.bible/api/v1/webhooks`
- Auth: none required

The only write on this API. Registers an https endpoint to be told when the knowledge base is re-ingested, instead of polling /changelog.

The response carries a secret, shown once and never again: it signs every delivery and authorises reading and deleting this subscription.

The URL must be https and must resolve to a public address. Redirects are not followed.

## Query parameters

- `sandbox` boolean

## Request body

- WebhookRegistration
  - `url` string, uri, required: Must be https, and must resolve to a public address. Private, loopback and link-local addresses are refused, including a public hostname that resolves to one.
  - `events` string[]: Omit for all events.

## Response `200`

Sandbox: validated, nothing stored.

- WebhookCreated
  - `subscription` Webhook
    - `id` string, uuid
    - `url` string, uri
    - `events` string[]
    - `createdAt` string, date-time
    - `status` 'active' | 'failing' | 'disabled'
    - `failures` integer: Consecutive failures. Ten disables the subscription.
    - `lastDeliveryAt` string, date-time, nullable
    - `lastResult` string, nullable
  - `secret` string: Shown once. Signs every delivery, and authorises GET and DELETE.
  - `sandbox` boolean: Present and true when nothing was stored.
  - `note` string

## Other responses

- `201`: Registered. Carries the secret, once.
- `400`: The reference or parameter could not be parsed.
- `429`: Too many registrations, or the registrar is full.
- `503`: The subscription store is unreachable. The read API is unaffected.

---

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