create_webhook_endpoint
Register an outbound webhook endpoint for the token's team. The signing secret is returned in this response only.
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.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
A client that honours annotations asks a person before running it. It reaches beyond Subscriby: a connector, a provider or a member.
Arguments
name*stringA label for the endpoint, shown in the dashboard.
url*stringThe https URL Subscriby posts events to. Must resolve to a public address; http and private-network targets are refused.
events*string[]Event names to deliver, from subscriby://enums/webhook-event. At least one.
project_idstringoptionalOptional project UUID: deliver only that project's events. Omit for every project of the team.
allowed_ipsstring[]optionalOptional 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_activebooleanoptionalWhether deliveries start right away. Defaults to true.
What it returns
{ "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.
How it fails
VALIDATION_FAILEDper 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_FOUNDunknown project_id, or a project outside the token's scope.
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks webhook-endpoint:create.
How is this guide?
Last updated on
Observability Tools
Where to look when something did not happen: webhook endpoints and their deliveries, the activity log of every mutation, and the status of a job another tool queued.
delete_webhook_endpoint
Remove an outbound webhook endpoint. Destructive — an integration listening on it goes dark at once; its delivery log is kept.