webhooks/

Webhook registrations — declare webhooks the realm wants to receive. When the realm is installed and the host has a public URL, these are registered with the external service.

Registration runs under the same trust tier as apis/: marketplace realms cannot interpolate a credential into register.args or call a directly networked tool holding a durable secret. The host binds registration and callback authentication to the world, context, access-policy revision, full realmDigest, source-registration generation, run-as principal, and grant revision. Callback routing also verifies the current worldEpoch. The templated form below is local/first-party compatibility syntax.

webhooks/github-issues.yml

- name: github-issues
  description: "Receive GitHub issue events"
  source: github
  events: [issues, issue_comment]
  action: webhook-github-issue
  register:
    tool: create_repository_webhook
    args:
      owner: "{{owner}}"
      repo: "{{repo}}"
      config:
        url: "{{webhook_base_url}}/api/v1/webhooks/github-issues"
        content_type: json
        secret: "{{GITHUB_WEBHOOK_SECRET}}"
      events: ["issues", "issue_comment"]

Field	Required	Description
name	Yes	Webhook identifier
description	No	What events this webhook handles
source	Yes	Source identifier (matches webhook endpoint path)
events	No	Event types to subscribe to
action	Yes	Action name to execute when webhook fires
register	No	Auto-registration config (tool + args)
register.tool	Yes (if register)	Tool to call for registration
register.args	Yes (if register)	Arguments with {{template}} variables

Template variables in register.args are resolved from:

• World config (config.yml)
• Credential store (secrets set by the user)
• Well-known variables: {{webhook_base_url}}, {{owner}}, {{repo}}

The bare-webhook flow — payload arrives, gets wrapped in a WebhookEvent, the named action fires — stays as documented above. For richer integration that emits typed signals into the host’s consequence engine, use events/ (next section).