FeaturesSolutionsEnterprisePricing
Join the Alpha
HomeFeaturesSolutionsPricing
EnterprisePrivacyTerms
Join the waitlistSign in

Claude Managed Agents webhooks

Stream Claude Managed Agents session events into the ledger.

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>)

#What Mesh does with each event

Anthropic eventResult in Mesh
session.status_run_startedRecords the session as running, writes a STATUS ledger entry ("session started"), and tries to link the session to a Mesh agent.
session.status_run_endedMarks the session ended and writes a STATUS ledger entry ("session ended").
Any other event typeAccepted 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 endpointCause and fix
404 Not foundThe 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 pageOnly organization admins can view or change webhook settings.
Events arrive but the agent is not shown liveThe session is unlinked. Name the Mesh agent to match the managed agent, or send claudeManagedSessionId when the agent pairs.

#Next steps