claude-managed-agents-webhooks

Name: claude-managed-agents-webhooks
Author: hookdeck

80stars10forks

How to install claude-managed-agents-webhooks?

hookdeck/webhook-skills/claude-managed-agents-webhooks

$npx -y skills add hookdeck/webhook-skills --skill claude-managed-agents-webhooks

Installs into the current project.

Summary

Receive and verify Anthropic Claude Managed Agents (CMA) webhooks. Use when setting up Claude Managed Agents webhook handlers, debugging signature verification, or handling agent session and vault events like session.status_idled, session.status_terminated, session.thread_created

Files · 1

View on GitHub

SKILL.md

1	# Claude Managed Agents Webhooks
2
3	## When to Use This Skill
4
5	- Setting up Claude Managed Agents (CMA) webhook handlers
6	- Debugging Anthropic webhook signature verification failures
7	- Handling agent session state changes (`session.status_idled`, `session.status_terminated`)
8	- Reacting to multiagent thread events (`session.thread_created`, `session.thread_idled`)
9	- Processing vault and credential events (`vault.created`, `vault_credential.refresh_failed`)
10	- Replacing long-poll loops on the Sessions API with push notifications
11
12	## Essential Code (USE THIS)
13
14	CMA webhooks follow the [Standard Webhooks](https://www.standardwebhooks.com/) 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.
15
16	### Express Webhook Handler
17
18	```javascript
19	const express = require('express');
20	const crypto = require('crypto');
21
22	const app = express();
23
24	// Standard Webhooks signature verification for Claude Managed Agents
25	function verifyClaudeSignature(payload, webhookId, webhookTimestamp, webhookSignature, secret) {
26	if (!webhookId \|\| !webhookTimestamp \|\| !webhookSignature \|\| !webhookSignature.includes(',')) {
27	return false;
28	}
29
30	// Reject payloads older than 5 minutes to prevent replay attacks
31	const currentTime = Math.floor(Date.now() / 1000);
32	const timestampDiff = currentTime - parseInt(webhookTimestamp);
33	if (timestampDiff > 300 \|\| timestampDiff < -300) {
34	return false;
35	}
36
37	// webhook-signature can carry multiple space-separated "v1,<sig>" pairs
38	const payloadStr = payload instanceof Buffer ? payload.toString('utf8') : payload;
39	const signedContent = `${webhookId}.${webhookTimestamp}.${payloadStr}`;
40
41	// whsec_ prefix wraps a base64-encoded 32-byte key
42	const secretKey = secret.startsWith('whsec_') ? secret.slice(6) : secret;
43	const secretBytes = Buffer.from(secretKey, 'base64');
44
45	const expectedSignature = crypto
46	.createHmac('sha256', secretBytes)
47	.update(signedContent, 'utf8')
48	.digest('base64');
49
50	return webhookSignature.split(' ').some(pair => {
51	const [version, signature] = pair.split(',');
52	if (version !== 'v1' \|\| !signature) return false;
53	try {
54	return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
55	} catch {
56	return false;
57	}
58	});
59	}
60
61	// CRITICAL: Use express.raw() for webhook endpoint - signature is over raw bytes
62	app.post('/webhooks/claude-managed-agents',
63	express.raw({ type: 'application/json' }),
64	async (req, res) => {
65	const webhookId = req.headers['webhook-id'];
66	const webhookTimestamp = req.headers['webhook-timestamp'];
67	const webhookSignature = req.headers['webhook-signature'];
68
69	if (!verifyClaudeSignature(
70	req.body,
71	webhookId,
72	webhookTimestamp,
73	webhookSignature,
74	process.env.ANTHROPIC_WEBHOOK_SIGNING_KEY
75	)) {
76	return res.status(400).send('Invalid signature');
77	}
78
79	const event = JSON.parse(req.body.toString());
80
81	// CMA payloads carry the event type under data.type, not the top-level type
82	switch (event.data?.type) {
83	case 'session.status_idled':
84	console.log('Session idled:', event.data.id);
85	// Fetch the full session: client.beta.sessions.retrieve(event.data.id)
86	break;
87	case 'session.status_terminated':
88	console.log('Session terminated:', event.data.id);
89	break;
90	case 'session.thread_created':
91	console.log('Multiagent thread created:', event.data.id);
92	break;
93	case 'vault_credential.refresh_failed':
94	console.log('Vault credential refresh failed:', event.data.id);
95	break;
96	default:
97	console.log('Unhandled event:', event.data?.type);
98	}
99
100	res.status(200).json({ received: true });
101	}
102	);
103	```
104
105	### Python (FastAPI) Webhook Handler
106
107	```python
108	import os
109	import hmac
110	import hashlib
111	import base64
112	import time
113	from fastapi import FastAPI, Request, HTTPException, Header
114
115	app = FastAPI()
116
117	def verify_claude_signature(
118	payload: bytes,
119	webhook_id: str,
120	webhook_timestamp: str,
121	webhook_signature: str,
122	secret: str,
123	) -> bool:
124	if not webhook

People who liked this also viewed

6 picks

Type

claude-managed-agents-webhooks

80stars10forks

View on GitHub

How to install claude-managed-agents-webhooks?

hookdeck/webhook-skills/claude-managed-agents-webhooks

$npx -y skills add hookdeck/webhook-skills --skill claude-managed-agents-webhooks

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Claude Managed Agents Webhooks
2
3	## When to Use This Skill
4
5	- Setting up Claude Managed Agents (CMA) webhook handlers
6	- Debugging Anthropic webhook signature verification failures
7	- Handling agent session state changes (`session.status_idled`, `session.status_terminated`)
8	- Reacting to multiagent thread events (`session.thread_created`, `session.thread_idled`)
9	- Processing vault and credential events (`vault.created`, `vault_credential.refresh_failed`)
10	- Replacing long-poll loops on the Sessions API with push notifications
11
12	## Essential Code (USE THIS)
13
14	CMA webhooks follow the [Standard Webhooks](https://www.standardwebhooks.com/) 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.
15
16	### Express Webhook Handler
17
18	```javascript
19	const express = require('express');
20	const crypto = require('crypto');
21
22	const app = express();
23
24	// Standard Webhooks signature verification for Claude Managed Agents
25	function verifyClaudeSignature(payload, webhookId, webhookTimestamp, webhookSignature, secret) {
26	if (!webhookId \|\| !webhookTimestamp \|\| !webhookSignature \|\| !webhookSignature.includes(',')) {
27	return false;
28	}
29
30	// Reject payloads older than 5 minutes to prevent replay attacks
31	const currentTime = Math.floor(Date.now() / 1000);
32	const timestampDiff = currentTime - parseInt(webhookTimestamp);
33	if (timestampDiff > 300 \|\| timestampDiff < -300) {
34	return false;
35	}
36
37	// webhook-signature can carry multiple space-separated "v1,<sig>" pairs
38	const payloadStr = payload instanceof Buffer ? payload.toString('utf8') : payload;
39	const signedContent = `${webhookId}.${webhookTimestamp}.${payloadStr}`;
40
41	// whsec_ prefix wraps a base64-encoded 32-byte key
42	const secretKey = secret.startsWith('whsec_') ? secret.slice(6) : secret;
43	const secretBytes = Buffer.from(secretKey, 'base64');
44
45	const expectedSignature = crypto
46	.createHmac('sha256', secretBytes)
47	.update(signedContent, 'utf8')
48	.digest('base64');
49
50	return webhookSignature.split(' ').some(pair => {
51	const [version, signature] = pair.split(',');
52	if (version !== 'v1' \|\| !signature) return false;
53	try {
54	return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
55	} catch {
56	return false;
57	}
58	});
59	}
60
61	// CRITICAL: Use express.raw() for webhook endpoint - signature is over raw bytes
62	app.post('/webhooks/claude-managed-agents',
63	express.raw({ type: 'application/json' }),
64	async (req, res) => {
65	const webhookId = req.headers['webhook-id'];
66	const webhookTimestamp = req.headers['webhook-timestamp'];
67	const webhookSignature = req.headers['webhook-signature'];
68
69	if (!verifyClaudeSignature(
70	req.body,
71	webhookId,
72	webhookTimestamp,
73	webhookSignature,
74	process.env.ANTHROPIC_WEBHOOK_SIGNING_KEY
75	)) {
76	return res.status(400).send('Invalid signature');
77	}
78
79	const event = JSON.parse(req.body.toString());
80
81	// CMA payloads carry the event type under data.type, not the top-level type
82	switch (event.data?.type) {
83	case 'session.status_idled':
84	console.log('Session idled:', event.data.id);
85	// Fetch the full session: client.beta.sessions.retrieve(event.data.id)
86	break;
87	case 'session.status_terminated':
88	console.log('Session terminated:', event.data.id);
89	break;
90	case 'session.thread_created':
91	console.log('Multiagent thread created:', event.data.id);
92	break;
93	case 'vault_credential.refresh_failed':
94	console.log('Vault credential refresh failed:', event.data.id);
95	break;
96	default:
97	console.log('Unhandled event:', event.data?.type);
98	}
99
100	res.status(200).json({ received: true });
101	}
102	);
103	```
104
105	### Python (FastAPI) Webhook Handler
106
107	```python
108	import os
109	import hmac
110	import hashlib
111	import base64
112	import time
113	from fastapi import FastAPI, Request, HTTPException, Header
114
115	app = FastAPI()
116
117	def verify_claude_signature(
118	payload: bytes,
119	webhook_id: str,
120	webhook_timestamp: str,
121	webhook_signature: str,
122	secret: str,
123	) -> bool:
124	if not webhook

People who liked this also viewed

6 picks

Type