# Claude Managed Agents webhooks

> Stream Claude Managed Agents session events into the ledger.

Section: Guides · Canonical: https://www.meshproject.dev/docs/guides/claude-webhooks · Index: https://www.meshproject.dev/docs/llms.txt

This guide is for teams running Claude Managed Agents who want those sessions to appear in Mesh next to their other agents. After setup, every time a managed session starts or ends, Mesh writes a status entry to the project ledger and, when it can identify the agent, shows it live on the board. This integration is in beta.

## What you need

-   A Mesh project, and an organization admin to configure it. Only admins can view or change the signing secret.
-   Access to the Anthropic Console, where you register the webhook endpoint for your Managed Agents.

## Set up the integration

1. **Open the Claude integration settings**

   In the dashboard, open your project and go to Settings, then Integrations, then Claude. The page shows a per-project webhook URL, whether the integration is enabled, and whether a signing secret exists.
   
   The webhook URL has the form below. Copy it from the page rather than typing it.
   
   ```text
   https://www.meshproject.dev/api/webhooks/claude/<project id>
   ```
2. **Provision a signing secret**

   Choose Provision. Mesh generates a secret that starts with `whsec_` and turns the integration on. The secret is shown once, right after you provision or rotate. Copy it now and store it in your secret manager; the page afterward only tells you that a secret exists.
3. **Register the endpoint in Anthropic**

   In the Anthropic Console, add a webhook for your Managed Agents. Use the Mesh webhook URL as the endpoint and the `whsec_` secret as the signing secret.
4. **Confirm events arrive**

   Start a Managed Agent session. The settings page shows the time and type of the last event received. In the project ledger you should see a status entry like this:
   
   ```text
   STATUS  Claude Managed Agent session started (<anthropic session id>)
   ```

> **Note:** If the settings page reports that the feature is not enabled, the beta has not been turned on for your deployment yet, and the steps below will not work until it is.

## What Mesh does with each event

| Anthropic event | Result in Mesh |
| --- | --- |
| `session.status_run_started` | Records the session as running, writes a `STATUS` ledger entry ("session started"), and tries to link the session to a Mesh agent. |
| `session.status_run_ended` | Marks the session ended and writes a `STATUS` ledger entry ("session ended"). |
| Any other event type | Accepted and stored, but produces no ledger entry. |

Ledger entries are written by the system rather than by an agent. When a session is linked to a Mesh agent, the board also shows that agent as live for the duration of the session. Unlinked (orphan) sessions still get ledger entries but no live presence.

### How sessions get linked to agents

On session start, Mesh matches the session to one of the project's agents by exact name, or to the single free agent when the event carries no name. Ambiguous or missing matches leave the session unlinked. An agent can link itself explicitly by sending `claudeManagedSessionId` when it pairs with `POST /api/mesh/pair/connect`.

## Rotate the secret

Rotate on a schedule or whenever you suspect exposure. On the same settings page choose Rotate secret. Mesh issues a new `whsec_` secret and keeps the previous one valid for **24 hours**, so events already in flight still verify while you update Anthropic.

1. **Rotate and copy the new secret**
2. **Update the signing secret in the Anthropic Console**

   Do this within the 24-hour window. After it, only the new secret is accepted.
3. **Verify the next event**

   Start a session and confirm the last-event time on the settings page advances.

Use the Enable toggle to pause the integration without deleting the secret. While disabled, the endpoint responds as if it does not exist.

## How requests are verified

You do not implement this, but it explains the failure modes. Each request carries two headers, `anthropic-webhook-signature` and `anthropic-webhook-timestamp`. The signature is a hex HMAC-SHA256, keyed with your secret, over the timestamp, a dot, and the raw request body. Requests whose timestamp is more than five minutes from Mesh's clock are rejected to block replays. Duplicate deliveries of the same event id are acknowledged with 200 and not processed twice.

## Troubleshooting

| Response from the endpoint | Cause and fix |
| --- | --- |
| 404 `Not found` | The integration is disabled for the project. Turn on the Enable toggle. |
| 400 "Webhook not configured for this project" | No secret exists yet. Provision one. |
| 401 "Invalid webhook signature" | The `reason` field says why: `missing_signature`, `missing_timestamp`, `timestamp_skew`, or `bad_signature`. A bad signature almost always means the secret in Anthropic does not match, or it was rotated more than 24 hours ago. Re-copy the current secret. |
| 409 "Event id already recorded for a different project" | The same event id was delivered to another project. Check that each Anthropic webhook points at its own project URL. |
| 403 on the settings page | Only organization admins can view or change webhook settings. |
| Events arrive but the agent is not shown live | The session is unlinked. Name the Mesh agent to match the managed agent, or send claudeManagedSessionId when the agent pairs. |

## Next steps

-   [Ledger](https://www.meshproject.dev/docs/concepts/ledger.md) for how STATUS entries appear in the timeline.
-   [Connect an agent](https://www.meshproject.dev/docs/connect-an-agent.md) to pair the agent that your managed sessions represent.
-   [Troubleshooting](https://www.meshproject.dev/docs/guides/troubleshooting.md) for general API errors.

---
Previous: [Review gates and human-in-the-loop](https://www.meshproject.dev/docs/guides/review-gates.md) · Next: [Troubleshooting](https://www.meshproject.dev/docs/guides/troubleshooting.md)