claude-managed-agents-webhooks

Claude Managed Agents Webhooks

When to Use This Skill

• Setting up Claude Managed Agents (CMA) webhook handlers
• Debugging Anthropic webhook signature verification failures
• Handling agent session state changes (session.status_idled, session.status_terminated)
• Reacting to multiagent thread events (session.thread_created, session.thread_idled)
• Processing vault and credential events (vault.created, vault_credential.refresh_failed)
• Replacing long-poll loops on the Sessions API with push notifications

Essential Code (USE THIS)

CMA webhooks follow the Standard Webhooks spec. Every delivery carries three headers — webhook-id, webhook-timestamp, and webhook-signature — and is signed with HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw-body}. The signing secret is the whsec_-prefixed value shown once at endpoint creation. The Anthropic SDK exposes client.beta.webhooks.unwrap() which wraps the same verification. Manual verification is shown here because it works in every framework without an extra SDK dependency.

Express Webhook Handler

const express = require('express');
const crypto = require('crypto');

const app = express();

// Standard Webhooks signature verification for Claude Managed Agents
function verifyClaudeSignature(payload, webhookId, webhookTimestamp, webhookSignature, secret) {
  if (!webhookId || !webhookTimestamp || !webhookSignature || !webhookSignature.includes(',')) {
    return false;
  }

  // Reject payloads older than 5 minutes to prevent replay attacks
  const currentTime = Math.floor(Date.now() / 1000);
  const timestampDiff = currentTime - parseInt(webhookTimestamp);
  if (timestampDiff > 300 || timestampDiff < -300) {
    return false;
  }

  // webhook-signature can carry multiple space-separated "v1,<sig>" pairs
  const payloadStr = payload instanceof Buffer ? payload.toString('utf8') : payload;
  const signedContent = `${webhookId}.${webhookTimestamp}.${payloadStr}`;

  // whsec_ prefix wraps a base64-encoded 32-byte key
  const secretKey = secret.startsWith('whsec_') ? secret.slice(6) : secret;
  const secretBytes = Buffer.from(secretKey, 'base64');

  const expectedSignature = crypto
    .createHmac('sha256', secretBytes)
    .update(signedContent, 'utf8')
    .digest('base64');

  return webhookSignature.split(' ').some(pair => {
    const [version, signature] = pair.split(',');
    if (version !== 'v1' || !signature) return false;
    try {
      return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
    } catch {
      return false;
    }
  });
}

// CRITICAL: Use express.raw() for webhook endpoint - signature is over raw bytes
app.post('/webhooks/claude-managed-agents',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const webhookId = req.headers['webhook-id'];
    const webhookTimestamp = req.headers['webhook-timestamp'];
    const webhookSignature = req.headers['webhook-signature'];

    if (!verifyClaudeSignature(
      req.body,
      webhookId,
      webhookTimestamp,
      webhookSignature,
      process.env.ANTHROPIC_WEBHOOK_SIGNING_KEY
    )) {
      return res.status(400).send('Invalid signature');
    }

    const event = JSON.parse(req.body.toString());

    // CMA payloads carry the event type under data.type, not the top-level type
    switch (event.data?.type) {
      case 'session.status_idled':
        console.log('Session idled:', event.data.id);
        // Fetch the full session: client.beta.sessions.retrieve(event.data.id)
        break;
      case 'session.status_terminated':
        console.log('Session terminated:', event.data.id);
        break;
      case 'session.thread_created':
        console.log('Multiagent thread created:', event.data.id);
        break;
      case 'vault_credential.refresh_failed':
        console.log('Vault credential refresh failed:', event.data.id);
        break;
      default:
        console.log('Unhandled event:', event.data?.type);
    }

    res.status(200).json({ received: true });
  }
);