---
title: "Subscribe an https address to events"
method: POST
path: "/workspace/webhooks"
tags: ["Webhooks"]
---

# Subscribe an https address to events

`POST /workspace/webhooks`

## Request

- Base URL: `https://preflight.social/v1`
- URL: `https://preflight.social/v1/workspace/webhooks`
- Auth: HTTP bearer

Scope webhooks:write. The secret is shown once. Deliveries carry x-preflight-event, x-preflight-id, x-preflight-timestamp and x-preflight-signature-v2 (t=…,v2=hex HMAC-SHA256 of `${t}.${body}`); answer 2xx within 10 seconds or it is retried five times.

## Request body

- object
  - `url` string, uri, required: https and public.
  - `events` string[]: Defaults to both.

## Response `201`

Created, with the secret.

- Webhook
  - `id` string, uuid
  - `url` string, uri
  - `events` string[]
  - `secret` string: whsec_…, shown once, on creation only.
  - `createdAt` string, date-time

## Other responses

- `400`: The body did not validate (invalid_request; field says which).
- `401`: Missing, expired or unrecognised key.
- `402`: The plan's allowance: post_limit, upload_limit, file_too_large, channel_limit, api_not_on_plan, ai_limit, ai_not_in_plan. Carries limit and upgradeTo.
- `403`: The key lacks the scope for this call.

---

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