Webhooks - Mibyan Docs

Receive events from external services (GitHub, GitLab, JIRA, Stripe, etc.) and trigger Mibyan agent runs automatically. The webhook adapter runs an HTTP server that accepts POST requests, validates HMAC signatures, transforms payloads into agent prompts, and routes responses back to the source or to another configured platform. The agent processes the event and can respond by posting comments on PRs, sending messages to Telegram/Discord, or logging the result.

Quick Start

Enable via mibyan gateway setup or environment variables
Define routes in config.yaml or create them dynamically with mibyan webhook subscribe
Point your service at http://your-server:8644/webhooks/<route-name>

Setup

There are two ways to enable the webhook adapter.

Via setup wizard

mibyan gateway setup

Follow the prompts to enable webhooks, set the port, and set a global HMAC secret.

Via environment variables

Add to ~/.mibyan/.env:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # default
WEBHOOK_SECRET=your-global-secret

Verify the server

Once the gateway is running:

curl http://localhost:8644/health

Expected response:

{"status": "ok", "platform": "webhook"}

Configuring Routes

Routes define how different webhook sources are handled. Each route is a named entry under platforms.webhook.extra.routes in your config.yaml. Adapter settings (port, host, secret, routes) may also be written directly under platforms.webhook: — both spellings reach the adapter; a value nested under extra: wins if the same key appears in both places.

Route properties

Property	Required	Description
`events`	No	List of event types to accept (e.g. `["pull_request"]`). If empty, all events are accepted. Event type is read from `X-GitHub-Event`, `X-GitLab-Event`, or `event_type` in the payload.
`secret`	Yes	HMAC secret for signature validation. Falls back to the global `secret` if not set on the route. Set to `"INSECURE_NO_AUTH"` for testing only (skips validation).
`profile`	No	Profile authorized to execute this route when `gateway.multiplex_profiles` is enabled. Omit it for a default-profile-only route; set a profile name (for example `coder`) to bind the route and its secret to `/p/coder/webhooks/<route>`. Dynamic subscriptions set it with `mibyan webhook subscribe <name> --route-profile coder`.
`prompt`	No	Template string with dot-notation payload access (e.g. `{pull_request.title}`). If omitted, the full JSON payload is dumped into the prompt. Payload fields are untrusted — see Authenticated does not mean trusted.
`filters`	No	Declarative payload filters evaluated after auth/body/event filtering and before agent or direct delivery work. Non-matches return `{"status":"ignored","reason":"filter"}` with HTTP 200.
`script`	No	Filter/transform script under `~/.mibyan/scripts/`. The webhook payload is passed as JSON on stdin. JSON object stdout replaces the payload before templating; text stdout is exposed as `script_output`; empty stdout, `[SILENT]`, or a nonzero exit code ignores the webhook.
`skills`	No	List of skill names to load for the agent run.
`toolsets`	No	List of toolset keys (e.g. `["terminal", "file", "web"]`) that replaces the platform-level webhook toolset for runs triggered by this route only. Manual config edit only — not settable via `mibyan webhook subscribe`, so agent-created subscriptions cannot self-grant elevated tools. Names are validated the same way as `platform_toolsets` entries (unknown or platform-restricted names are dropped). See Per-route toolsets.
`deliver`	No	Where to send the response: `github_comment`, `telegram`, `discord`, `slack`, `signal`, `sms`, `whatsapp`, `matrix`, `mattermost`, `homeassistant`, `email`, `dingtalk`, `feishu`, `wecom`, `weixin`, `bluebubbles`, `qqbot`, or `log` (default).
`deliver_extra`	No	Additional delivery config — keys depend on `deliver` type (e.g. `repo`, `pr_number`, `chat_id`). Values support the same `{dot.notation}` templates as `prompt`.
`deliver_only`	No	If `true`, skip the agent entirely — the rendered `prompt` template becomes the literal message that gets delivered. Zero LLM cost, sub-second delivery. See Direct Delivery Mode for use cases. Requires `deliver` to be a real target (not `log`).
`cron_job`	No	Fire an existing cron job (by ID or name) on each event instead of starting a fresh webhook agent session. The rendered `prompt` becomes transient per-run context; the job’s own prompt, skills, model, and delivery settings apply. Mutually exclusive with `deliver_only`. See Event-Triggered Cron Jobs.
`coalesce`	No	Debounce rapid distinct events on the same logical entity into one agent run. Block with a required `key` (payload field or template identifying the entity, e.g. `pull_request.number`), optional `window_seconds` (quiet window, default 30) and `max_wait_seconds` (dispatch cap, default 300). See Event Coalescing. Mutually exclusive with `deliver_only` and `cron_job`.
`mirror_to_session`	No	Default `false`. When `true`, after a successful delivery to a chat platform the delivered message is also written into that chat’s session transcript (as a labelled user turn, the same way continuable cron briefs are), so when you reply in that chat the agent knows what it just sent you. See Replying to a delivery.

Full example

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "github-webhook-secret"
          prompt: |
            Review this pull request:
            Repository: {repository.full_name}
            PR #{number}: {pull_request.title}
            Author: {pull_request.user.login}
            URL: {pull_request.html_url}
            Diff URL: {pull_request.diff_url}
            Action: {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"
        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "New push to {repository.full_name} branch {ref}: {head_commit.message}"
          filters:
            - field: "ref"
              equals: "refs/heads/main"
          deliver: "telegram"

Payload Filters

Use filters when a provider sends a broad event stream but only some payloads should wake the agent or trigger deliver_only delivery. Filters run after signature validation, body parsing, and events, but before prompt rendering, idempotency, agent dispatch, or direct delivery.

platforms:
  webhook:
    extra:
      routes:
        todoist:
          events: ["item:updated"]
          secret: "todoist-secret"
          filters:
            - field: "payload.labels"
              contains: "mibyan"
            - any:
                - field: "payload.priority"
                  equals: 4
                - field: "payload.project_id"
                  in_file: "~/.mibyan/data/todoist/watchlist.json"
          prompt: "Todoist task changed: {payload.content}"

Supported operators:

exists: true|false
missing: true
equals / not_equals
contains for strings, lists, and dict keys
in for inline lists
in_file for JSON arrays, JSON objects (keys are used), or newline-delimited text files
regex
all, any, and not groups

Field paths use dot notation. payload.foo reads from a top-level payload object when one exists, or from the root webhook body for flat payloads. event / event_type match the resolved event type, and headers.<Name> reads request headers.

Event Coalescing

Providers often fire several distinct events for the same logical entity in quick succession — five rapid pushes to one pull request, a burst of edits to one ticket, a flapping monitoring alert. Each event carries a fresh delivery ID, so the idempotency cache cannot suppress them and every event wakes a separate agent run. Set coalesce on a route to debounce these into a single run per entity:

platforms:
  webhook:
    extra:
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "github-webhook-secret"
          coalesce:
            key: "{repository.full_name}#{pull_request.number}"
            window_seconds: 30      # quiet window (default 30)
            max_wait_seconds: 300   # dispatch cap (default 300)
          prompt: "Review PR #{pull_request.number}: {pull_request.title}"
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{pull_request.number}"

How it works:

Events are grouped per route by the rendered key. A bare dotted field (pull_request.number) or a full template ({repository.full_name}#{pull_request.number}) both work.
Each new event replaces the pending one and pushes the quiet-window timer back. When window_seconds pass with no new event, the group dispatches one agent run using the latest event’s payload, prompt, and delivery templates.
max_wait_seconds caps total buffering from the group’s first event, so a steady event stream cannot postpone dispatch forever.
When more than one event was coalesced, the prompt gets a short note telling the agent how many earlier events were superseded.
If the key does not resolve for an event (the payload lacks the field — e.g. an issue_comment event on a route keyed by pull_request.number), that event is dispatched immediately instead of being coalesced, so unrelated entities never collapse into one group. Pick a key present on every event type the route accepts.
Coalesced requests return HTTP 202 with {"status": "coalesced"}. Delivery-ID idempotency still runs first, so provider retries of the same delivery are dropped rather than counted.
Pending groups are flushed (dispatched immediately) when the adapter disconnects — a gateway reconnect or mibyan gateway stop — not dropped. Buffered events live in memory, so a hard process kill loses at most the current window’s buffered burst.
coalesce applies to agent-mode routes only; combining it with deliver_only or cron_job is rejected at startup.

Script Filters and Transforms

Use script when declarative filters are not enough. Scripts must live under ~/.mibyan/scripts/ for the active profile; relative paths resolve there, and path traversal outside that directory is blocked. .sh and .bash scripts run with bash, and all other extensions run with the current Python interpreter. The route payload is sent to stdin as JSON:

# ~/.mibyan/scripts/todoist-mibyan-label.py
import json
import sys

payload = json.load(sys.stdin)
labels = payload.get("payload", {}).get("labels", [])
if "mibyan" not in labels:
    print("[SILENT]")
    raise SystemExit(0)

payload["body"] = payload["payload"]["content"]
print(json.dumps(payload))

Script outcomes:

JSON object stdout replaces the payload used by prompt and deliver_extra.
Non-JSON text stdout is added to the payload as script_output.
Empty stdout, exact [SILENT], {"__mibyan_ignore__": true}, timeout, missing script, or nonzero exit code returns HTTP 200 with {"status":"ignored","reason":"script"}.

Prompt Templates

Prompts use dot-notation to access nested fields in the webhook payload:

{pull_request.title} resolves to payload["pull_request"]["title"]
{repository.full_name} resolves to payload["repository"]["full_name"]
{__raw__} — special token that dumps the entire payload as indented JSON (truncated at 4000 characters). Useful for monitoring alerts or generic webhooks where the agent needs the full context.
Missing keys are left as the literal {key} string (no error)
Nested dicts and lists are JSON-serialized and truncated at 2000 characters

You can mix {__raw__} with regular template variables:

prompt: "PR #{pull_request.number} by {pull_request.user.login}: {__raw__}"

If no prompt template is configured for a route, the entire payload is dumped as indented JSON (truncated at 4000 characters). The same dot-notation templates work in deliver_extra values.

Forum Topic Delivery

When delivering webhook responses to Telegram, you can target a specific forum topic by including message_thread_id (or thread_id) in deliver_extra:

webhooks:
  routes:
    alerts:
      events: ["alert"]
      prompt: "Alert: {__raw__}"
      deliver: "telegram"
      deliver_extra:
        chat_id: "-1001234567890"
        message_thread_id: "42"

If chat_id is not provided in deliver_extra, the delivery falls back to the home channel configured for the target platform.

GitHub PR Review (Step by Step)

This walkthrough sets up automatic code review on every pull request.

1. Create the webhook in GitHub

Go to your repository → Settings → Webhooks → Add webhook
Set Payload URL to http://your-server:8644/webhooks/github-pr
Set Content type to application/json
Set Secret to match your route config (e.g. github-webhook-secret)
Under Which events?, select Let me select individual events and check Pull requests
Click Add webhook

2. Add the route config

Add the github-pr route to your ~/.mibyan/config.yaml as shown in the example above.

3. Ensure `gh` CLI is authenticated

The github_comment delivery type uses the GitHub CLI to post comments:

gh auth login

4. Test it

Open a pull request on the repository. The webhook fires, Mibyan processes the event, and posts a review comment on the PR.

GitLab Webhook Setup

GitLab webhooks work similarly but use a different authentication mechanism. GitLab sends the secret as a plain X-Gitlab-Token header (exact string match, not HMAC).

1. Create the webhook in GitLab

Go to your project → Settings → Webhooks
Set the URL to http://your-server:8644/webhooks/gitlab-mr
Enter your Secret token
Select Merge request events (and any other events you want)
Click Add webhook

2. Add the route config

platforms:
  webhook:
    enabled: true
    extra:
      routes:
        gitlab-mr:
          events: ["merge_request"]
          secret: "your-gitlab-secret-token"
          prompt: |
            Review this merge request:
            Project: {project.path_with_namespace}
            MR !{object_attributes.iid}: {object_attributes.title}
            Author: {object_attributes.last_commit.author.name}
            URL: {object_attributes.url}
            Action: {object_attributes.action}
          deliver: "log"

Delivery Options

The deliver field controls where the agent’s response goes after processing the webhook event.

Deliver Type	Description
`log`	Logs the response to the gateway log output. This is the default and is useful for testing.
`github_comment`	Posts the response as a PR/issue comment via the `gh` CLI. Requires `deliver_extra.repo` and `deliver_extra.pr_number`. The `gh` CLI must be installed and authenticated on the gateway host (`gh auth login`).
`telegram`	Routes the response to Telegram. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`discord`	Routes the response to Discord. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`slack`	Routes the response to Slack. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`signal`	Routes the response to Signal. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`sms`	Routes the response to SMS via Twilio. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`whatsapp`	Routes the response to WhatsApp. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`matrix`	Routes the response to Matrix. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`mattermost`	Routes the response to Mattermost. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`homeassistant`	Routes the response to Home Assistant. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`email`	Routes the response to Email. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`dingtalk`	Routes the response to DingTalk. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`feishu`	Routes the response to Feishu/Lark. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`wecom`	Routes the response to WeCom. Uses the home channel, or specify `chat_id` in `deliver_extra`.
`weixin`	Routes the response to Weixin (WeChat). Uses the home channel, or specify `chat_id` in `deliver_extra`.
`bluebubbles`	Routes the response to BlueBubbles (iMessage). Uses the home channel, or specify `chat_id` in `deliver_extra`.

For cross-platform delivery, the target platform must also be enabled and connected in the gateway. If no chat_id is provided in deliver_extra, the response is sent to that platform’s configured home channel.

Replying to a delivery

By default a delivery is fire-and-forget: each webhook event runs in its own session, so if you reply to the delivered message in that chat, the agent there has no record of what was sent. Set mirror_to_session: true on the route (or pass --mirror-to-session to mibyan webhook subscribe) and the delivered text is also appended to the target chat’s session as [Webhook delivery: <route>] followed by the message, so a follow-up (“so he’s out?”) has the context.

The mirror is best-effort: it never fails the delivery, and it is skipped when the chat has no gateway session yet (nobody has talked to the agent there).
On a /p/<profile>/ route it is written into that profile’s session for the chat, never another profile’s.
The mirrored text enters the chat’s history as if you had sent it. On a deliver_only route it is the raw rendered payload, so only enable it for sources whose content you trust to sit in your conversation (your own services, not a public issue tracker).

Direct Delivery Mode

By default, every webhook POST triggers an agent run — the payload becomes a prompt, the agent processes it, and the agent’s response is delivered. This costs LLM tokens on every event. For use cases where you just want to push a plain notification — no reasoning, no agent loop, just deliver the message — set deliver_only: true on the route. The rendered prompt template becomes the literal message body, and the adapter dispatches it directly to the configured delivery target.

When to use direct delivery

External service push — Supabase/Firebase webhook fires on a database change → notify a user in Telegram instantly
Monitoring alerts — Datadog/Grafana alert webhook → push to a Discord channel
Inter-agent pings — Agent A notifies Agent B’s user that a long-running task finished
Background job completion — Cron job finishes → post result to Slack

Benefits:

Zero LLM tokens — the agent is never invoked
Sub-second delivery — a single adapter call, no reasoning loop
Same security as agent mode — HMAC auth, rate limits, idempotency, and body-size limits all still apply
Synchronous response — the POST returns 200 OK once delivery succeeds, or 502 if the target rejects it, so your upstream service can retry intelligently

Example: Telegram push from Supabase

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-secret"
      routes:
        antenna-matches:
          secret: "antenna-webhook-secret"
          deliver: "telegram"
          deliver_only: true
          prompt: "🎉 New match: {match.user_name} matched with you!"
          deliver_extra:
            chat_id: "{match.telegram_chat_id}"

Your Supabase edge function signs the payload with HMAC-SHA256 and POSTs to https://your-server:8644/webhooks/antenna-matches. The webhook adapter validates the signature, renders the template from the payload, delivers to Telegram, and returns 200 OK.

Example: Dynamic subscription via CLI

mibyan webhook subscribe antenna-matches \
  --deliver telegram \
  --deliver-chat-id "123456789" \
  --deliver-only \
  --prompt "🎉 New match: {match.user_name} matched with you!" \
  --description "Antenna match notifications"

Response codes

Status	Meaning
`200 OK`	Delivered successfully. Body: `{"status": "delivered", "route": "...", "target": "...", "delivery_id": "..."}`
`200 OK` (status=duplicate)	Duplicate `X-GitHub-Delivery` ID within the idempotency TTL (1 hour). Not re-delivered.
`401 Unauthorized`	HMAC signature invalid or missing.
`400 Bad Request`	Malformed JSON body.
`404 Not Found`	Unknown route name.
`413 Payload Too Large`	Body exceeded `max_body_bytes`.
`429 Too Many Requests`	Route rate limit exceeded.
`502 Bad Gateway`	Target adapter rejected the message or raised. The error is logged server-side; the response body is a generic `Delivery failed` to avoid leaking adapter internals.

Configuration gotchas

deliver_only: true requires deliver to be a real target. deliver: log (or omitting deliver) is rejected at startup — the adapter refuses to start if it finds a misconfigured route.
The skills field is ignored in direct delivery mode (no agent runs, so there’s nothing to inject skills into).
Template rendering uses the same {dot.notation} syntax as agent mode, including the {__raw__} token.
Idempotency uses the same X-GitHub-Delivery / X-Request-ID header — retries with the same ID return status=duplicate and do NOT re-deliver.

Event-Triggered Cron Jobs

Set cron_job on a route to fire an existing cron job whenever an event arrives — instead of polling on a fixed cadence or starting a fresh webhook agent session. This turns any scheduled job into an event-driven task: keep the schedule as a fallback sweep (or make it a rarely-firing one) and let the webhook fire it the moment something actually changes. How it works:

The event passes the same HMAC auth, rate limiting, events/filters/script filtering, and idempotency as any other route.
The route’s prompt template is rendered from the payload and injected into the job as transient per-run context (the same rail as cronjob(action='run', prompt=...) — the job’s stored prompt is never mutated).
The job fires through the same at-most-once claim the scheduler uses, so a webhook burst cannot double-fire a job that is already running, and the job’s own delivery target receives the output.

Example: fire a PR-review job on review feedback

platforms:
  webhook:
    enabled: true
    extra:
      routes:
        pr-feedback:
          events: ["pull_request_review"]
          secret: "github-webhook-secret"
          cron_job: "pr-review-sweeper"        # existing job ID or name
          prompt: |
            PR #{number} in {repository.full_name} received new review feedback
            from {review.user.login}: {review.body}

Via the CLI

mibyan webhook subscribe pr-feedback \
  --events "pull_request_review" \
  --cron-job "pr-review-sweeper" \
  --prompt "PR #{number} received feedback: {review.body}"

The job reference is validated when you create the subscription, so typos surface immediately.

Notes

cron_job and deliver_only are mutually exclusive (the adapter refuses to start if a route sets both). A cron job handles its own delivery.
The route-level deliver, deliver_extra, and skills fields are ignored on cron_job routes — the job’s own settings apply.
Paused/disabled jobs are not fired; the event is logged and dropped.
The POST returns 202 Accepted immediately; the job runs in the background.

Dynamic Subscriptions (CLI)

In addition to static routes in config.yaml, you can create webhook subscriptions dynamically using the mibyan webhook CLI command. This is especially useful when the agent itself needs to set up event-driven triggers.

Create a subscription

mibyan webhook subscribe github-issues \
  --events "issues" \
  --prompt "New issue #{issue.number}: {issue.title}\nBy: {issue.user.login}\n\n{issue.body}" \
  --deliver telegram \
  --deliver-chat-id "-100123456789" \
  --description "Triage new GitHub issues"

This returns the webhook URL and an auto-generated HMAC secret. Configure your service to POST to that URL.

List subscriptions

mibyan webhook list

Remove a subscription

mibyan webhook remove github-issues

Test a subscription

mibyan webhook test github-issues
mibyan webhook test github-issues --payload '{"issue": {"number": 42, "title": "Test"}}'

How dynamic subscriptions work

Subscriptions are stored in ~/.mibyan/webhook_subscriptions.json
The webhook adapter hot-reloads this file on each incoming request (mtime-gated, negligible overhead)
Static routes from config.yaml always take precedence over dynamic ones with the same name
Dynamic subscriptions use the same route format and capabilities as static routes (events, prompt templates, skills, delivery)
No gateway restart required — subscribe and it’s immediately live

Agent-driven subscriptions

The agent can create subscriptions via the terminal tool when guided by the webhook-subscriptions skill. Ask the agent to “set up a webhook for GitHub issues” and it will run the appropriate mibyan webhook subscribe command.

Per-route toolsets

Webhook agent runs default to a deliberately constrained toolset (web_search, web_extract, vision_analyze, clarify) because webhook payloads can carry untrusted third-party content — a public PR title or issue comment should never be able to prompt-inject its way into your terminal. For trusted routes — a localhost monitoring daemon pushing system alerts, an internal CI system — you can grant a wider toolset to that route only, without widening every other webhook route:

platforms:
  webhook:
    enabled: true
    extra:
      routes:
        oom-emergency:
          secret: "monitor-secret"
          prompt: "Memory emergency: {detail}. Diagnose with ps/free/py-spy and report."
          toolsets: ["terminal", "file", "code_execution", "web"]
          deliver: "telegram"

For dynamic subscriptions, add the toolsets key by editing ~/.mibyan/webhook_subscriptions.json directly:

{
  "oom-emergency": {
    "secret": "...",
    "prompt": "...",
    "toolsets": ["terminal", "file", "web"],
    "deliver": "telegram"
  }
}

Behavior and safety properties:

The route list replaces the platform-level webhook toolset resolution for that route’s runs (it is not merged).
Names are validated through the same path as platform_toolsets config — unknown names and platform-restricted toolsets are dropped.
mibyan webhook subscribe deliberately does not accept a toolsets flag. Granting elevated tools is a manual config-file edit, so an agent creating its own subscription at runtime cannot self-grant terminal.
Only grant elevated toolsets to routes whose senders you fully control, with a real HMAC secret. Anyone who can POST a validly-signed payload to that route is effectively running an agent with those tools.

Security

The webhook adapter includes multiple layers of security:

HMAC signature validation

The adapter validates incoming webhook signatures using the appropriate method for each source:

GitHub: X-Hub-Signature-256 header — HMAC-SHA256 hex digest prefixed with sha256=
GitLab: X-Gitlab-Token header — plain secret string match
Standard Webhooks: webhook-id, webhook-timestamp, and webhook-signature headers — signed content is {id}.{timestamp}.{raw_body} with a v1,<base64-hmac-sha256> signature
Generic (V2, recommended): X-Webhook-Signature-V2 + X-Webhook-Timestamp headers — HMAC-SHA256 hex digest of <timestamp>.<body>. The timestamp (Unix seconds) must be within ±300 seconds of the server clock, which prevents captured requests from being replayed later.
Generic (V1, legacy): X-Webhook-Signature header — raw HMAC-SHA256 hex digest of the body only. Still accepted for backward compatibility, but it has no replay protection (a captured request replays indefinitely); the gateway logs a deprecation warning once per route. Switch senders to V2.

If a secret is configured but no recognized signature header is present, the request is rejected.

Secret is required

Every route must have a secret — either set directly on the route or inherited from the global secret. Routes without a secret cause the adapter to fail at startup with an error. For development/testing only, you can set the secret to "INSECURE_NO_AUTH" to skip validation entirely. When multi-profile routing is enabled, the route’s profile field also binds that secret to one execution target. A route without profile is default-profile-only. A request carrying a valid route signature is still rejected if its /p/<profile>/ prefix does not match the route binding. INSECURE_NO_AUTH is only accepted when the gateway is bound to a loopback host (127.0.0.1, localhost, ::1). If it is combined with a non-loopback bind such as 0.0.0.0 or a LAN IP, the adapter refuses to start — this prevents accidentally exposing an unauthenticated endpoint on a public interface.

Rate limiting

Each route is rate-limited to 30 requests per minute by default (fixed-window). Configure this globally:

platforms:
  webhook:
    extra:
      rate_limit: 60  # requests per minute

Requests exceeding the limit receive a 429 Too Many Requests response.

Idempotency

Delivery IDs (from X-GitHub-Delivery, svix-id, webhook-id, X-Request-ID, or a random per-request ID) are cached for 1 hour. Duplicate deliveries (e.g. webhook retries) are silently skipped with a 200 response, preventing duplicate agent runs.

Body size limits

Payloads exceeding 1 MB are rejected before the body is read. Configure this:

platforms:
  webhook:
    extra:
      max_body_bytes: 2097152  # 2 MB

Authenticated does not mean trusted

HMAC validation authenticates the sender, not the content. A valid signature only proves the request came from a party holding the route’s secret (e.g. GitHub). It says nothing about who wrote the business fields inside the payload — PR titles, commit messages, issue descriptions, and any other upstream text are authored by arbitrary third parties and must be treated as untrusted.This is the same trust model that applies to everything the agent reads: web pages, files, and tool output are all untrusted input. Mibyan does not — and cannot reliably — sanitize untrusted text with a blocklist; phrasing, encoding, and translation make that trivially bypassable. The trust boundary is the agent’s capability surface, not the input channel. Harden there:

Sandbox the runtime. Run the gateway with the Docker or SSH terminal backend (or in a VM) when exposed to the internet, so a hijacked turn cannot touch the host.
Scope the toolset. Disable terminal, file, and outbound-action tools on webhook-triggered sessions if the route only needs to read and summarize. Fewer capabilities means a smaller blast radius if a payload field carries injected instructions.
Keep approvals on for any destructive or outbound operation, so an injected instruction cannot act unattended.
Template narrowly. Prefer a specific prompt with named fields ({pull_request.title}) over {__raw__} or an empty template that dumps the whole payload, so only the fields you intend reach the prompt.

Troubleshooting

Webhook not arriving

Verify the port is exposed and accessible from the webhook source
Check firewall rules — port 8644 (or your configured port) must be open
Verify the URL path matches: http://your-server:8644/webhooks/<route-name>
Use the /health endpoint to confirm the server is running

Signature validation failing

Ensure the secret in your route config exactly matches the secret configured in the webhook source
For GitHub, the secret is HMAC-based — check X-Hub-Signature-256
For GitLab, the secret is a plain token match — check X-Gitlab-Token
Check gateway logs for Invalid signature warnings

Event being ignored

Check that the event type is in your route’s events list
GitHub events use values like pull_request, push, issues (the X-GitHub-Event header value)
GitLab events use values like merge_request, push (the X-GitLab-Event header value)
If events is empty or not set, all events are accepted

Agent not responding

Run the gateway in foreground to see logs: mibyan gateway run
Check that the prompt template is rendering correctly
Verify the delivery target is configured and connected

Duplicate responses

The idempotency cache should prevent this — check that the webhook source is sending a delivery ID header (X-GitHub-Delivery, svix-id, webhook-id, or X-Request-ID)
Delivery IDs are cached for 1 hour

`gh` CLI errors (GitHub comment delivery)

Run gh auth login on the gateway host
Ensure the authenticated GitHub user has write access to the repository
Check that gh is installed and on the PATH

Environment Variables

Variable	Description	Default
`WEBHOOK_ENABLED`	Enable the webhook platform adapter	`false`
`WEBHOOK_PORT`	HTTP server port for receiving webhooks	`8644`
`WEBHOOK_SECRET`	Global HMAC secret (used as fallback when routes don’t specify their own)	(none)

​Quick Start

​Setup

​Via setup wizard

​Via environment variables

​Verify the server

​Configuring Routes

​Route properties

​Full example

​Payload Filters

​Event Coalescing

​Script Filters and Transforms

​Prompt Templates

​Forum Topic Delivery

​GitHub PR Review (Step by Step)

​1. Create the webhook in GitHub

​2. Add the route config

​3. Ensure gh CLI is authenticated

​4. Test it

​GitLab Webhook Setup

​1. Create the webhook in GitLab

​2. Add the route config

​Delivery Options

​Replying to a delivery

​Direct Delivery Mode

​When to use direct delivery

​Example: Telegram push from Supabase

​Example: Dynamic subscription via CLI

​Response codes

​Configuration gotchas

​Event-Triggered Cron Jobs

​Example: fire a PR-review job on review feedback

​Via the CLI

​Notes

​Dynamic Subscriptions (CLI)

​Create a subscription

​List subscriptions

​Remove a subscription

​Test a subscription

​How dynamic subscriptions work

​Agent-driven subscriptions

​Per-route toolsets

​Security

​HMAC signature validation

​Secret is required

​Rate limiting

​Idempotency

​Body size limits

​Authenticated does not mean trusted

​Troubleshooting

​Webhook not arriving

​Signature validation failing

​Event being ignored

​Agent not responding

​Duplicate responses

​gh CLI errors (GitHub comment delivery)

​Environment Variables

Quick Start

Setup

Via setup wizard

Via environment variables

Verify the server

Configuring Routes

Route properties

Full example

Payload Filters

Event Coalescing

Script Filters and Transforms

Prompt Templates

Forum Topic Delivery

GitHub PR Review (Step by Step)

1. Create the webhook in GitHub

2. Add the route config

3. Ensure `gh` CLI is authenticated

4. Test it

GitLab Webhook Setup

1. Create the webhook in GitLab

2. Add the route config

Delivery Options

Replying to a delivery

Direct Delivery Mode

When to use direct delivery

Example: Telegram push from Supabase

Example: Dynamic subscription via CLI

Response codes

Configuration gotchas

Event-Triggered Cron Jobs

Example: fire a PR-review job on review feedback

Via the CLI

Notes

Dynamic Subscriptions (CLI)

Create a subscription

List subscriptions

Remove a subscription

Test a subscription

How dynamic subscriptions work

Agent-driven subscriptions

Per-route toolsets

Security

HMAC signature validation

Secret is required

Rate limiting

Idempotency

Body size limits

Authenticated does not mean trusted

Troubleshooting

Webhook not arriving

Signature validation failing

Event being ignored

Agent not responding

Duplicate responses

`gh` CLI errors (GitHub comment delivery)

Environment Variables