@hookdeck/openclaw

Reliable webhooks for OpenClaw. Put the Hookdeck Event Gateway in front of your agent's inbound webhooks: signature verification for 145+ providers, event deduplication, a durable queue that survives restarts, and agent tools for inspecting and replaying deliveries.

openclaw plugins install clawhub:@hookdeck/openclaw

OpenClaw's built-in webhook support keeps core minimal: one shared token for every webhook, no provider signature verification, no deduplication, and no queue: if the gateway is down when an event arrives, the event is gone. Requests for per-provider auth (#4977) and for targeting an agent by id (#5868) were closed as not planned, with plugins named as the intended extension point. Per-agent routing did land separately, via webhook mappings (#9130).

This plugin fills those gaps by making Hookdeck the ingress layer for your agent:

• Verification: Hookdeck verifies provider signatures at the source; the plugin verifies Hookdeck's signature on every delivery. Unverified requests are rejected before dispatch.
• Deduplication: deliveries are tracked by event ID and attempt number in an append-only JSONL ledger. A delivery is admitted only when its attempt number exceeds the highest recorded for that event ID. Retries of handled events return 200 so Hookdeck stops resending.
• Durability: the ledger survives crashes. On restart, orphaned in-flight entries are settled and handed back to Hookdeck via POST /events/{id}/retry. Hookdeck is the authoritative work queue; the plugin never loses events it has acknowledged.
• Three dispatch modes: wake (enqueue a system event, optionally request an immediate heartbeat), taskflow (accept TaskFlow action envelopes from automation platforms), and agent (render the raw provider payload into a prompt for an isolated agent turn, no envelope required).
• Routing and filtering: per-route source mapping, session keys, and payload filters (equals, in, exists). Non-matching events return 200 with {"ignored": true}.
• CLI supervision: manages a hookdeck listen child process per route (requires Hookdeck CLI 2.4.0 or later), with binary shadowing detection. http and none transport modes are available for reachable gateways and manual provisioning.
• Catch-up: if requests arrived during an outage longer than a configurable threshold, they're replayed after restart.

1. Create a Hookdeck account (free tier works) and install the Hookdeck CLI version 2.4.0 or later.

2. Install the plugin:

   openclaw plugins install clawhub:@hookdeck/openclaw

3. Add your Hookdeck project signing secret (from the dashboard Settings page) and a route to ~/.openclaw/openclaw.json:

   {
     "plugins": {
       "entries": {
         "hookdeck": {
           "enabled": true,
           "config": {
             "signingSecret": "<your Hookdeck signing secret>",
             "routes": {
               "stripe": {
                 "source": "stripe",
                 "dispatch": {
                   "mode": "wake",
                   "sessionKey": "main",
                   "text": "Stripe event received ({eventId})"
                 }
               }
             }
           }
         }
       }
     }
   }

   signingSecret also accepts a secret reference, so the value need not sit in the config file: { "source": "env", "provider": "env", "id": "HOOKDECK_SIGNING_SECRET" }.

4. Restart the OpenClaw gateway. The plugin verifies, deduplicates, and dispatches events from your stripe source.

Receiving requires only the signing secret. Adding an apiKey unlocks provisioning (hookdeck_setup), pause/resume, replay, and issue management.

Your agent can operate its own webhook infrastructure. Read-only diagnostics:

Action tools, each with a rail on the destructive path:

Set tools.allowMutations: false to restrict agents to read-only access.

Webhook payloads are third-party input, and this plugin treats them that way:

• Provider verification happens at the Hookdeck source; failures reject at the request layer before OpenClaw is involved.
• Two distinct secrets: signingSecret authenticates Hookdeck's deliveries to OpenClaw; provider credentials (e.g. Stripe's whsec_...) are configured at the Hookdeck source and never touch your machine.
• Signatures and tokens are redacted from logs and tool output; API keys are scrubbed from CLI output; payload bodies are truncated and labelled as opt-in data.
• Payload text is data, never instructions.
• In CLI transport mode, no inbound port is exposed on the machine running OpenClaw.

• Agent turns are fire-and-forget: acknowledged when the run starts, not when it completes.
• Signatures authenticate the body only, not headers.
• JSON and form-encoded bodies only.
• List endpoints return the first page only.

The README covers the common path. Everything else lives in docs/:

openclaw plugins install --link ./hookdeck-openclaw
npm test           # no Gateway or Hookdeck account required
npm run test:package   # loads the packed tarball in a real Gateway
npm run test:e2e:all   # 38 scenarios against a real project (needs HOOKDECK_TEST_API_KEY)

Releasing, the live suites and what CI covers are in CONTRIBUTING.md.

• Using Hookdeck with OpenClaw: full architecture walkthrough
• Hookdeck docs
• Hookdeck Console: inspect webhooks without an account

Issues and PRs welcome.