---
title: "Call the createWebhookEndpoint MCP tool"
method: POST
path: "/api/v1/actions/createWebhookEndpoint"
tags: ["Actions"]
---

# Call the createWebhookEndpoint MCP tool

`POST /api/v1/actions/createWebhookEndpoint`

## Request

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

Create a new outbound webhook endpoint. url must be https; a private, local, or internal host is refused. Pass at least one event type in events (see getWebhookEndpoints or the "known" list on an unknown_event error for the currently subscribable types). Optional category_filters narrows reply.* events to specific reply classifications; omit to receive every event you subscribed to. Optional campaign_filters restricts delivery to events for those campaign ids only (must be campaigns already in this workspace); omit or leave empty for every campaign. From this surface the endpoint is created INACTIVE and its signing secret is never returned: the user opens Settings > Developer > Webhooks (ui_url in the result), rotates the secret on the new endpoint to see it once, then enables it. The REST API creates it active and returns the secret directly for server-side automation.

Called through the Actions bridge: the response is that tool's own result, wrapped as `{ data: <tool result> }` under HTTP 200. Billing, daily-cap, and confirm-step outcomes are embedded INSIDE `data`, never remapped to an HTTP status (see the templated `/api/v1/actions/{toolName}` operation above for the full protocol, and `x-mcp-actions` for this tool's machine-readable scope/cap/confirm_behavior fields). Authentication, request-shape, and optional idempotency-protocol failures still use their documented non-200 statuses.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `url` string, uri, required: The https endpoint that will receive event payloads.
  - `events` string[], required: Event types to subscribe to. Unknown values are refused, with the current known list returned.
  - `category_filters` string[]: Optional: only deliver reply.* events matching these reply classifications.
  - `campaign_filters` string[]: Optional: only deliver events for these campaign ids. Omit for every campaign.

## Response `200`

The result of calling this tool.

- object
  - `data` unknown, required
  - `error` unknown, required

## Other responses

- `400`: The request body was not a JSON object (code invalid_request), or Idempotency-Key is malformed (code invalid_idempotency_key).
- `401`: Missing or invalid API key. Send `Authorization: Bearer rmcp_...` (code unauthorized).
- `403`: This tool is out of the key’s granted scope (code insufficient_scope).
- `409`: This Idempotency-Key has an unresolved in-flight or ambiguous result (code request_in_flight). Reconcile before using a new key.
- `422`: This Idempotency-Key was already used with a different request body (code idempotency_key_reuse).
- `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`: Unhandled server error (code internal_error).

---

[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/11682826692b?raw)