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

# Create a webhook endpoint

`POST /api/v1/webhooks`

## Request

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

The plaintext signing secret is returned exactly once, in this response.

## Request body

- object
  - `url` string, uri, required: Must be https and not resolve to a private host.
  - `events` string[], required
  - `category_filters` string[], nullable
  - `campaign_filters` string[], nullable: Only deliver events for these campaign ids (must already belong to this workspace). Omit or null for every campaign.
  - `description` string

## Response `201`

Created.

- object
  - `data` WebhookEndpointWithSecret, required: Only returned by POST /webhooks (create) and POST /webhooks/{id}/rotate-secret. The plaintext `secret` is shown exactly once here and is never retrievable again; rotate to get a new one.
    - `id` string, required
    - `workspace_id` string, required
    - `url` string, uri, required
    - `events` string[], required
    - `category_filters` string[], nullable, required
    - `campaign_filters` string[], nullable, required
    - `kind` 'webhook', required
    - `is_active` boolean, required
    - `disabled_reason` string, nullable, required
    - `consecutive_failures` integer, required
    - `description` string, nullable, required
    - `created_by` string, nullable, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `secret` string, required
  - `error` unknown, required

## Other responses

- `400`: Missing url/events (code invalid_request), or a validation failure: invalid_url, https_required, private_host, invalid_events, invalid_category_filters, or invalid_campaign_filters.
- `401`: Missing or invalid API key. Send `Authorization: Bearer rmcp_...` (code unauthorized).
- `402`: Workspace billing is blocked; mutating requests are refused (code billing_blocked).
- `403`: The key's granted scopes do not satisfy this endpoint's minimum required scope (code insufficient_scope).
- `429`: Rate limited: shared `mcp:ip:{ip}` (600/60s) or `mcp:key:{keyId}` (120/60s) bucket, the SAME buckets the MCP endpoint uses (code rate_limited).
- `500`: Create failed (code internal_error).
- `503`: The billing-status check itself failed (DB error): fails closed rather than letting a blocked workspace through; safe to retry (code billing_check_failed).

---

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