Webhooks

Every OpenClaw instance can expose a webhook so external systems or other agents running inside Claworc can send it a message over HTTP and receive the agent’s reply synchronously. Each instance has its own webhook URL, its own set of API keys, and its own call history.

The webhook accepts a session_name so repeated calls with the same name continue the same conversation with the agent.

Where to find it

Open an OpenClaw instance and scroll the Settings tab to the Webhook section, just below Enabled models. The section is visible to admins and team managers.

Each instance has two webhook URLs:

• Public URL — reachable from any caller that can hit your Claworc dashboard. Use this for external systems (Continuous Integration jobs, automation tools, partner integrations).
• Private URL — reachable only from inside Claworc, at http://127.0.0.1:<gateway-port>/webhooks/<uuid>. Use this when one OpenClaw instance needs to call another. It is not exposed to the public internet.

Whether a given API key works on the public URL, the private URL, or both is controlled by the key’s visibility, not the URLs themselves. The URLs are always shown; the keys decide who gets in.

API keys

The webhook is disabled until at least one API key is configured. Once you add a key, the matching URL starts accepting calls.

Adding a key

1. Click + Add key.
2. Enter a Label describing the caller (for example, zapier, partner-x, master agent). The label is required.
3. Optionally tick Accessible only to other AI agents within Claworc to make the key inaccessible from the Internet.
4. Click Save.

If you regenerate the API key, the previous value stops working immediately, so any caller still using it will receive 401 until you give them the new value.

Calling the webhook

Send a POST request to either URL with a bearer token in the Authorization header.

JSON body

curl -X POST "https://claworc.example.com/webhooks/<instance-uuid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  -d '{"session_name":"<session name>","message":"<message>"}'

Fields

• session_name — required. Must match ^[A-Za-z0-9._-]+$ (letters, digits, dashes, underscores, and dots). Calls with the same session_name continue the same conversation with the agent.
• message — the text the OpenClaw agent will receive.

Response

The response is plain text — the agent’s reply, with no JSON wrapper. The HTTP request stays open until the agent finishes generating the response, so size your HTTP client’s read timeout to match the longest reply you expect.

Webhook events

You can see webhooks usage by clicking Events in the top-right of the Webhook section to open the events modal. It lists the last 100 calls to this instance’s webhook. Each row shows:

• When — the request timestamp.
• Visibility — public or private, depending on which URL was hit.
• Source IP — the caller’s IP address (taken from X-Forwarded-For if present).
• Session — the session_name supplied in the request.
• Status — the HTTP status code returned to the caller.
• Duration — how long the call took, in milliseconds.
• Bytes (in/out) — request body size and response body size.
• Key — the last four characters of the API key that authenticated the call.
• Error — the error message, if any.

Use the events list to spot misconfigured callers (repeated 401s), measure response time, or confirm that an expected integration is hitting the right instance.

Common HTTP status codes

• 200 — success; the body contains the agent’s reply.
• 400 — the request was malformed, the session_name was missing, or it contained invalid characters.
• 401 — the bearer token did not match any key for this endpoint’s visibility.
• 404 — no instance with that UUID exists, or no keys of the matching visibility are configured. Claworc intentionally returns 404 rather than 401 in the latter case so callers cannot probe for valid instance UUIDs.
• 502 — the agent failed to produce a reply. The response body contains the error message.