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 Zuse Bifrost 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, and allowed_ips to pin the consumer's addresses.
The secret is returned once
The response carries secret alongside the endpoint row. It is the key every
delivery to this endpoint is signed with, it is never readable again, not by
get_webhook_endpoint,
not in the application, 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 Zuse Bifrost: a repository host, a pipeline, a chat or an email.
Arguments
name*stringA label for the endpoint, 3 to 100 characters, shown on the webhooks settings page.
url*stringThe https URL events are posted to. Must resolve to a public address; http and private-network targets are refused.
events*string[]Event names to deliver, from zusegenius://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": "Delivery board", "url": "https://hooks.example.test/zusegenius", "project_id": null, "events": ["project.created", "project.status_changed"], "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-10-26T09:20:00+00:00", "updated_at": "2026-10-26T09:20:00+00:00", "secret": "whsec_..." }, "meta": {}}Every event name must be one the token could subscribe to: each event requires the ability of its family (project.* needs project:view, team.* needs team:view, and so on), which is checked at registration. The zusegenius://enums/webhook-event resource lists every event with the ability it needs.
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