Overview

A Webhook receives an HTTP request sent by an external system and passes the task in that request to an agent for processing. Once configured, events such as monitoring alerts, order changes, repository activity, or email notifications can trigger PlugClaw to analyze information, produce a result, or use available tools without requiring someone to open a conversation and send the message manually.

The external system is the request sender. The PlugClaw Gateway provides the Webhook endpoint, and an agent allowed by allowedAgentIds processes the task. The Webhook only delivers the event to PlugClaw. What the agent can ultimately do still depends on its model, Skills, tools, and permissions.

Event payloads, authentication methods, and retry behavior vary across external systems. This guide first uses a local test request to trigger the main agent and verify Webhook reception, token authentication, and task creation. A real third-party integration must also follow that system's Webhook documentation, adapt its request payload, and use an endpoint the sender can reach.

Treat the Webhook endpoint and token as a service entry point and access credential. Do not expose the real token in a public page, conversation, or screenshot, and do not make the Webhook available to untrusted callers. External access also requires appropriate HTTPS protection, network restrictions, and credential handling. A local example address should never be copied directly into an external system.

Before You Begin

Confirm the following information before configuring the Webhook:

Sender          The external system that will call the Webhook
Target agent    The agent that will process the request; this guide uses main
Endpoint        A protected PlugClaw Gateway address the sender can reach
Auth token      A random string used to authenticate the request
Payload         How the external event will be converted into an agent-readable message

To use an agent other than main, create that agent first and confirm its agent ID. See Agent Management for the agent creation and usage process.

Webhook settings are stored in openclaw.json. Back up the file before editing it. Merge the example into the existing configuration instead of replacing model, Skill, channel, or other settings already present in the file.

Generate a Webhook Token

Run the following command in the terminal on the PlugOS device to generate a random token:

openssl rand -hex 32

Copy the generated string and store it securely. It acts as the Webhook password and must be used both in the PlugClaw configuration and in requests from the external system. Generate a dedicated Webhook token; do not reuse the Gateway token, Gateway password, or a credential from another service.

If the terminal reports that openssl is unavailable, do not substitute a short or predictable password. Use another trusted credential-generation tool available in the current environment to create a sufficiently long random token.

Add the Webhook Configuration

Open openclaw.json, merge the following hooks block into the existing configuration, and replace YOUR_HOOK_TOKEN with the token generated above:

{
  "hooks": {
    "enabled": true,
    "path": "/hooks",
    "token": "YOUR_HOOK_TOKEN",
    "allowedAgentIds": [
      "main"
    ],
    "allowRequestSessionKey": false
  }
}

The settings have the following purposes:

enabled                  Enables or disables Webhook reception
path                     Sets the Webhook path prefix on the Gateway
token                    Provides the authentication token required from callers
allowedAgentIds          Lists the agent IDs that Webhook requests may trigger
allowRequestSessionKey   Controls whether callers may choose a session identifier

This example permits only the main agent and does not allow the caller to choose a session identifier. Unless caller-selected session reuse is specifically required, keep allowRequestSessionKey set to false to reduce the risk of an external request entering an unintended session.

Save the configuration and restart the Gateway so it reloads the Webhook settings. See Gateway Management for the restart procedure. If the Gateway no longer starts, restore the previous openclaw.json backup and check the JSON structure and quotation marks around the token.

Send a Local Test Request

Test from the PlugOS device that runs the Gateway first. A local test separates Webhook configuration problems from external network-access problems. Run:

curl -X POST "http://localhost:45650/hooks/agent" \
  -H "Authorization: Bearer YOUR_HOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Please reply: Webhook configuration succeeded",
    "agentId": "main",
    "name": "Webhook Test"
  }'

Replace YOUR_HOOK_TOKEN with the actual hooks.token value from openclaw.json. localhost:45650 means that the request sender and the Gateway are on the same device. If the Gateway uses a different port, replace the port with the current value.

The request fields mean:

message   The task content passed to the agent
agentId   The agent ID requested for the task
name      The name shown for this task in conversations or records

After running the command, open the conversation page and look for the Webhook Test task. You can also use the runtime logs to confirm that the request was received. A successful HTTP response only means that the task entered the agent-run workflow; it does not mean the task has finished. Confirm that the main agent actually received and processed the task before treating the local Webhook test as successful.

allowedAgentIds limits the agents a Webhook may ultimately use. Keep main in the list for this example. To target a different agent, confirm that its ID is valid and add it to the allowlist first. An unknown or disallowed ID may interact with default-agent routing and the allowlist, so do not rely on fallback behavior to select the processing agent.

If no task appears, confirm that the URL includes the complete /hooks/agent path, the Authorization header uses the Bearer format, the token matches exactly, and the target agent is allowed by allowedAgentIds.

Connect an External System

After the local test succeeds, configure the Webhook in the external system. An external caller cannot use localhost to reach PlugClaw and must use a protected endpoint available from its network. This guide does not derive an external Webhook address from the device IP. The correct address depends on the PlugClaw network deployment. Use an endpoint limited to a trusted network, or provide access through a trusted reverse proxy and HTTPS. Do not expose the Gateway port directly to the public internet without understanding the security impact.

The external system must include the authentication token in the same way as the test request and convert its event data into fields PlugClaw accepts, including message. If the sender retries failed events, review its official retry behavior so the same event does not unintentionally trigger the task multiple times.

Use a harmless test event after the integration is configured. Compare the sender's delivery record, the resulting PlugClaw conversation, and the runtime logs. The external integration is confirmed only when all three refer to the same event.

To stop receiving Webhooks temporarily, set enabled to false and restart the Gateway. If the token may have been exposed, generate a new one, replace the old value in both PlugClaw and the sender, and restart the Gateway so the old token no longer works.