IdentyClaw Webhooks Gateway Component

OpenClaw plugin — RODiT-signed webhook ingress on /hooks/wake and /hooks/agent

Part of IdentyClaw.

IdentyClaw component service: OpenClaw plugin for RODiT-signed webhook ingress on agent gateways (/hooks/wake, /hooks/agent) and outbound delivery via send_rodit_webhook. Webhook signing and verification use @rodit/rodit-auth-be per the IdentyClaw OpenClaw integration guide (MCP discovery: api.identyclaw.com/.well-known/mcp).

[!IMPORTANT] Production deploy: For nginx TLS, A2A peer messaging, signed webhooks, and GitHub Actions CI, use identyclaw-agents instead of wiring plugins manually on the gateway host.

Role in the IdentyClaw stack

identyclaw-tools (identity) + identyclaw-a2a (peer map) + identyclaw-webhooks (this repo)

Recommended together via identyclaw-agents deploy — the template installs all three plugins and nginx routes /hooks/* to the gateway.

Install this plugin when Passport-authenticated agents need to receive signed webhooks from IdentyClaw (HOLA validation outcomes, liveness pings) or send signed webhooks to peers — not for IdentyClaw API login, HOLA creation, or A2A messaging (use identyclaw-tools and identyclaw-a2a for those).

Inbound webhooks require x-signature and x-timestamp headers and Ed25519 verification through @rodit/rodit-auth-be, matching the receiver checklist in the OpenClaw integration guide. Outbound send_rodit_webhook resolves peer gateway bases from the A2A outbound agent map, persisted A2A peers cache, or IdentyClaw identity API (metadata.webhook_url).

Set Passport webhook_url to the gateway base URL only (no hook path). IdentyClaw and peer SDKs append /hooks/agent or /hooks/wake when sending.

📦 Installation

From ClawHub:

openclaw plugins install clawhub:@identyclaw/openclaw-identyclaw-webhooks-plugin

From npm:

openclaw plugins install @identyclaw/openclaw-identyclaw-webhooks-plugin

From git:

openclaw plugins install https://github.com/discernible-io/openclaw-identyclaw-webhooks-plugin.git

During development you can also install from a local checkout:

cd openclaw-identyclaw-webhooks-plugin
npm install
npm run build
openclaw plugins install .

Restart the gateway:

openclaw gateway restart

Follow the setup in IdentyClaw usage, Receiving webhooks (inbound), and/or Sending webhooks (outbound).

Related IdentyClaw artifacts

identyclaw-webhooks shares NEAR Passport credential files with identyclaw-a2a and identyclaw-tools. Outbound peer resolution reads plugins.entries.identyclaw-a2a.config.outbound.agents (or legacy a2a).

Required for outbound delivery: send_rodit_webhook peer resolution depends on the A2A plugin outbound agent map (or identity API fallback). Pair with identyclaw-tools for Passport session login and HOLA on the same host.

Recommended deploy: identyclaw-agents installs this plugin, pins versions in env.local, and nginx routes /hooks/wake and /hooks/agent to the OpenClaw upstream. Run ./identyclaw.sh test after deploy for the full smoke suite (A2A + webhooks).

🔐 IdentyClaw usage (RODiT webhooks)

This component implements the OpenClaw-side webhook receiver per the IdentyClaw OpenClaw integration guide: verify Ed25519 origin signatures, correlate webhooks to login sessions, and accept events from the Passport API or peer agents.

Environment variables

Webhook verification and outbound signing use the NEAR Passport credentials file (same layout as gennearaccount and identyclaw-agents bootstrap):

IDENTYCLAW_* env vars remain used by identyclaw-tools (HOLA, DID, identity) on the same host — they are not required for webhook signature verification.

Keep credentials in env or secrets files — not in openclaw.json.

Embedding in OpenClaw chat / gateway (quiet mode)

When this plugin is enabled, OpenClaw loads it in chat (node dist/index.js chat) as well as the gateway. @rodit/rodit-auth-be logs JSON to stdout and node-config warns on stderr at import time, which can appear inline in the chat TUI.

This plugin lazy-loads rodit-auth-be only on the first inbound webhook or outbound send_rodit_webhook call, and applies quiet embed defaults before import:

Host env vars always win. Override per-plugin with logLevel in openclaw.json:

"identyclaw-webhooks": {
  "enabled": true,
  "config": {
    "logLevel": "error"
  }
}

Plugin id and config

Plugin id: identyclaw-webhooks

{
  "plugins": {
    "entries": {
      "identyclaw-webhooks": {
        "enabled": true,
        "config": {
          "endpoints": ["/hooks/wake", "/hooks/agent"],
          "logLevel": "error",
          "persistPeerRegistry": false,
          "peerRegistryPath": "/home/node/.openclaw/cache/peer-registry.json"
        }
      }
    }
  }
}

Passport webhook_url alignment

On startup the plugin warms up the RODiT client and reads your Passport metadata.webhook_url. If identyclaw-a2a inbound.publicBaseUrl is set and differs from Passport metadata, a warning is logged — align them so IdentyClaw API delivery and peer discovery advertise the same gateway host.

Example metadata (gateway base only):

{
  "webhook_url": "https://my-openclaw.example.com",
  "webhook_cidr": "203.0.113.0/24"
}

IdentyClaw POST target: https://my-openclaw.example.com/hooks/agent

See doc:reference:token-metadata and doc:reference:openclaw-integration-guide via IdentyClaw MCP.

📥 Receiving webhooks (inbound)

Set up

1. Enable identyclaw-webhooks in openclaw.json (see Plugin id and config).
2. Register Passport webhook_url pointing at your gateway host (base URL only).
3. Expose the gateway over TLS (reverse proxy, Tailscale Funnel, etc.).
4. Restart the gateway after config changes.

The plugin registers each configured endpoint with auth: "plugin" — OpenClaw gateway auth is bypassed; RODiT signature verification is the gate.

Verification flow

For each POST:

1. Require x-signature and x-timestamp headers.
2. Resolve signer public key via SDK extractWebhookSignerKey (headers, with fallback to StateManager.getPeerBase64urlJwkPublicKey() from prior login).
3. Call authenticate_webhook from @rodit/rodit-auth-be.
4. Extract signed session_id and cross-reference against SessionManager.hasSession.
5. Record receipt metadata and return JSON with sessionId and sessionKnown.

/hooks/wake payload

Accepts JSON with text, or event (with optional nested data.text), or nested data.text. Optional mode: "now" (default) or "next-heartbeat".

{
  "text": "Peer validated HOLA",
  "mode": "now"
}

On success, triggers a gateway heartbeat when mode is "now".

/hooks/agent payload

Accepts any signed JSON body. Returns { ok: true, endpoint: "agent", accepted: true, sessionId, sessionKnown }. Map event and data fields to agent prompts per the OpenClaw integration guide.

Example from IdentyClaw POST /api/testhola (development):

{
  "event": "testhola_validation_success",
  "data": {
    "peerTokenId": "abc123def456",
    "serverTokenId": "xyz789uvw012",
    "recipient": "MUNDO",
    "timestamp": "2026-04-24T18:30:00.000Z",
    "endpoint": "/api/testhola"
  }
}

Test helper: /hooks/_receipts

Receipts persist under /home/node/.openclaw/cache/webhook-receipts.json (best-effort).

Error responses

📤 Sending webhooks (outbound)

Prerequisites

Configure at least one outbound peer in identyclaw-a2a (or legacy a2a), or rely on dynamic resolution by Passport token_id:

{
  "plugins": {
    "entries": {
      "identyclaw-a2a": {
        "enabled": true,
        "config": {
          "outbound": {
            "auth": { "provider": "rodit" },
            "agents": {
              "agent-b": {
                "url": "http://openclaw-agent-b:18789/.well-known/agent-card.json"
              }
            }
          }
        }
      },
      "identyclaw-webhooks": {
        "enabled": true
      }
    }
  }
}

Peer resolution order for send_rodit_webhook:

1. outbound.agents.<peerId> in identyclaw-a2a config
2. A2A persisted peers ({OPENCLAW_STATE_DIR}/a2a/outbound/peers.json)
3. This plugin's peer registry cache
4. GET /api/identity/token/{token_id}/full — prefers metadata.webhook_url over contactUri

Tool: send_rodit_webhook

Sign and POST a RODiT webhook to a peer after an optional delay. The SDK stamps session correlation via sessionRoditId when this peer issued the recipient's JWT.

Enable in sandbox when needed:

"sandbox": {
  "tools": {
    "alsoAllow": ["send_rodit_webhook"]
  }
}

Outbound TLS verification follows identyclaw-a2a outbound.tlsSkipVerify (development only).

💡 Use Cases

• Receive IdentyClaw HOLA validation webhooks on OpenClaw and trigger agent tasks on /hooks/agent
• Wake the main session with signed liveness pings on /hooks/wake after Passport events
• Send delayed signed webhooks to A2A peers without manual SDK scripting
• Correlate inbound webhooks to active login sessions for multi-peer gateways
• Resolve peer gateway URLs from Passport metadata.webhook_url when not preconfigured in A2A outbound map

✨ Features

• RODiT-signed inbound webhooks — Ed25519 verification via @rodit/rodit-auth-be on /hooks/wake and /hooks/agent
• Session correlation — extract signed session_id, report sessionKnown against live login sessions
• Outbound send_rodit_webhook tool — sign and deliver webhooks to peers with configurable delay and hook path
• Peer resolution — A2A outbound map, persisted peers cache, identity API metadata.webhook_url fallback
• Passport metadata alignment — startup check of webhook_url vs A2A publicBaseUrl
• Quiet embed mode — lazy-load rodit-auth-be with library-quiet defaults for chat TUI
• Test helper — GET|DELETE /hooks/_receipts for integration debugging

🌐 HTTP Endpoints

Configurable via endpoints in plugin config. Default paths match the IdentyClaw OpenClaw integration guide.

External URL layout (same host)

Webhooks share the gateway host with OpenClaw hooks and A2A:

agent-a.example.com/hooks/wake          → This plugin (heartbeat)
agent-a.example.com/hooks/agent           → This plugin (agent task)
agent-a.example.com/a2a                   → identyclaw-a2a JSON-RPC
agent-a.example.com/.well-known/agent-card.json  → A2A discovery

Requirements

• OpenClaw gateway ≥ 2026.5.27
• Node ≥ 22.19.0
• NEAR Passport credentials (NEAR_CREDENTIALS_FILE_PATH or secrets/near-credentials/*.json)
• For outbound send_rodit_webhook: plugins.entries.identyclaw-a2a.config.outbound.agents peer map (or resolvable token_id)

Publish to ClawHub

See PUBLISH.md:

npm run prepare:publish
npm run publish:clawhub:dry-run
npm run publish:clawhub

🛠️ Development

Install dependencies and build:

npm install
npm run build

Install the plugin from a local checkout:

openclaw plugins install /absolute/path/to/openclaw-identyclaw-webhooks-plugin

Restart the gateway:

openclaw gateway restart

Smoke tests

📄 License

Apache-2.0 — Copyright (c) Discernible IO. See LICENSE.

discernible.io · OpenClaw integration guide · MCP discovery

🔗 Cross-links

• This repo: discernible-io/openclaw-identyclaw-webhooks-plugin
• A2A plugin (required for send_rodit_webhook peer resolution): discernible-io/openclaw-a2a-idc-plugin
• IdentyClaw tools: discernible-io/openclaw-identyclaw-plugin
• RODiT SDK: discernible-io/sdk — @rodit/rodit-auth-be at runtime
• Deploy template: discernible-io/identyclaw-agents — installs this plugin, nginx /hooks/* routing, ./identyclaw.sh test
• Webhook contract (MCP): doc:reference:openclaw-integration-guide · .well-known/mcp
• Credential layout: gennearaccount · identyclaw-agents