create_webhook_endpoint

Purpose

Register a URL for Subscriby to post events to, with the event names it should receive. The endpoint belongs to the token's team; pass project_id to deliver only one project's events.

The secret is returned once

The response carries secret alongside the endpoint row. It is the HMAC key every delivery to this endpoint is signed with, it is never readable again — not by get_webhook_endpoint, not by the dashboard — and it can only be replaced with rotate_webhook_endpoint_secret. Hand it to the consumer immediately. This is the one exception to the server's rule that a secret is never surfaced.

The URL must be https and resolve to a public address; http and private-network targets are refused. Deliveries start at once unless is_active is false.

Required ability

webhook-endpoint:create

Input schema

{
  "type": "object",
  "required": ["name", "url", "events"],
  "properties": {
    "name": {
      "type": "string",
      "description": "A label for the endpoint, shown in the dashboard."
    },
    "url": {
      "type": "string",
      "description": "The https URL Subscriby posts events to. Must resolve to a public address; http and private-network targets are refused."
    },
    "events": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Event names to deliver, from subscriby://enums/webhook-event. At least one."
    },
    "project_id": {
      "type": "string",
      "description": "Optional project UUID: deliver only that project's events. Omit for every project of the team."
    },
    "allowed_ips": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Optional list of IP addresses or CIDR ranges the endpoint host may resolve to; a delivery whose host resolves outside the list is dead-lettered without being posted."
    },
    "is_active": {
      "type": "boolean",
      "description": "Whether deliveries start right away. Defaults to true."
    }
  }
}

Output shape

{
  "data": {
    "id": "c62a08f4-1b7d-4e35-9860-a37f5d21e0b9",
    "name": "CRM sync",
    "url": "https://hooks.example.com/subscriby",
    "project_id": null,
    "events": ["subscription.created", "subscription.cancelled"],
    "is_active": true,
    "disabled_at": null,
    "allowed_ips": [],
    "failure_count": 0,
    "consecutive_failures": 0,
    "last_success_at": null,
    "last_failure_at": null,
    "created_at": "2026-09-06T09:20:00+00:00",
    "secret": "whsec_..."
  }
}

Every event name must be one the token could subscribe to: each event requires the ability of its family (subscription.* needs project-subscription:view, and so on), which is checked at registration.

Example prompts

"Register https://hooks.example.com/subscriby for every subscription event, named 'CRM sync'."

"Create a webhook endpoint that receives only support.conversation.opened for project 7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13."

"Set up an endpoint for payment failures, paused until we've deployed the handler."

Failure modes

VALIDATION_FAILED — per field: an http or private-network URL, an empty or unknown events list, an event the token cannot subscribe to, an allowed_ips entry that is neither an IP address nor a CIDR range.
RESOURCE_NOT_FOUND — unknown project_id, or a project outside the token's scope.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks webhook-endpoint:create.

list_webhook_endpoints — what the team already has.
test_webhook_endpoint — check the consumer end to end.
rotate_webhook_endpoint_secret — the only way to get a new secret.
Webhook endpoints API — the REST equivalent.
Webhook security — verifying the signature.