导航|地址|刷新
Webhooks
图
Skip to contentDocumentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt
Use this file to discover all available pages before exploring further.



DocsDirectoryAPISDKsChangelog

Search

Log in






Agents

/




Overview


Getting started


Quick start

Add to existing project

Testing your Agents






Concepts


What are agents?

Conversation state and memory

Tools

Calling LLMs

Using Agents with Workflows


Agentic patterns


Overview

Human-in-the-loop patterns

Long-running agents










Communication channels



Chat


Chat agents

Autonomous responses

Client SDK





Voice

Email

Slack


Webhooks


Overview

Push notifications










Tools


Sandbox

MCP

Browser

AI Search


Agentic Payments


Overview

Charge for HTTP content


x402


Overview

Charge for HTTP content

Charge for MCP tools

Pay from Agents SDK

Pay from coding tools





MPP (Machine Payments Protocol)






Code Mode


Overview

Create a durable Code Mode runtime

AI SDK integration

Use Code Mode with TanStack AI

Browser-owned tools

MCP

OpenAPI

How Code Mode works

Code Mode API reference










Harnesses


Overview


Think


Overview

Getting started

Configuration

Tools

Actions

Lifecycle hooks

Client tools

Messengers

Channels

Scheduled tasks

Workflows

Sub-agent RPC and programmatic turns

Programmatic submissions

Durable recovery










Runtime


Agents API


Lifecycle


Agent class internals

Callable methods

Store and sync state

Sessions

getCurrentAgent()






Communication


Routing

WebSockets

HTTP and Server-Sent Events

Chat SDK

Protocol messages

Readonly connections






Execution


Sub-agents

Schedule tasks

Durable execution with fibers

Queue tasks

Retries

Run Workflows

Agents as tools

Agent Skills






Operations


Configuration

Cross-domain authentication

Using AI Models

Observability










Examples


Chat agent

Slack agent

Voice agent

Browser agent

Email agent






Model Context Protocol (MCP)


Overview


APIs


MCP handler APIs

McpAgent

McpClient






Protocol


Tools

Authorization

Transport

MCP governance






Guides


Build MCP client

Build a Remote MCP server

Test a Remote MCP Server

Securing MCP servers

Connect to an MCP server

Handle OAuth with MCP servers

Migrate to MCP SDK v2

Build a single-tool Code Mode MCP server

Build a search and execute MCP server






Cloudflare


MCP server portals ↗


Cloudflare's own MCP servers


Overview

Cloudflare Community MCP Server









Code Mode MCP server patterns






Platform


Limits






Agent resources


Agent setup ↗

Cloudflare Skills ↗

Code Mode MCP Server ↗

Domain-specific MCP Servers ↗MCP

Agents llms.txt ↗

Agents llms-full.txt ↗

Cloudflare Docs llms.txt ↗

Cloudflare Docs llms-full.txt ↗













Home

/Agents

/Communication channels

/Webhooks



Webhooks


Last updated Jun 3, 2026|Copy as Markdown|View as Markdown|Agent setup

OverviewQuick startUse cases Developer tools E-commerce and payments Communication and notifications IoT and infrastructure SaaS integrationsRouting webhooks to agents Extract entity from payload Extract entity from URL Extract entity from headersSignature verification HMAC-SHA256 pattern Provider-specific headersProcessing webhooks The onRequest handlerStoring webhook events Event table schema Cleanup old events Query eventsReal-time broadcastingPatterns Event deduplication Respond quickly, process asynchronously Multi-provider routingSending outgoing webhooksSecurity best practicesCommon webhook providersNext steps




Receive webhook events from external services and route them to dedicated agent instances. Each webhook source (repository, customer, device) can have its own agent with isolated state, persistent storage, and real-time client connections.


Quick start







import { Agent, getAgentByName, routeAgentRequest } from "agents";// Agent that handles webhooks for a specific entityexport class WebhookAgent extends Agent { async onRequest(request) { if (request.method !== "POST") { return new Response("Method not allowed", { status: 405 }); } // Verify the webhook signature const signature = request.headers.get("X-Hub-Signature-256"); const body = await request.text(); if ( !(await this.verifySignature(body, signature, this.env.WEBHOOK_SECRET)) ) { return new Response("Invalid signature", { status: 401 }); } // Process the webhook payload const payload = JSON.parse(body); await this.processEvent(payload); return new Response("OK", { status: 200 }); } async verifySignature(payload, signature, secret) { if (!signature) return false; const encoder = new TextEncoder(); const key = await crypto.subtle.importKey( "raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"], ); const signatureBytes = await crypto.subtle.sign( "HMAC", key, encoder.encode(payload), ); const expected = `sha256=${Array.from(new Uint8Array(signatureBytes)) .map((b) => b.toString(16).padStart(2, "0")) .join("")}`; return signature === expected; } async processEvent(payload) { // Store event, update state, trigger actions... }}// Route webhooks to the right agent instanceexport default { async fetch(request, env) { const url = new URL(request.url); // Webhook endpoint: POST /webhooks/:entityId if (url.pathname.startsWith("/webhooks/") && request.method === "POST") { const entityId = url.pathname.split("/")[2]; const agent = await getAgentByName(env.WebhookAgent, entityId); return agent.fetch(request); } // Default routing for WebSocket connections return ( (await routeAgentRequest(request, env)) || new Response("Not found", { status: 404 }) ); },};

import { Agent, getAgentByName, routeAgentRequest } from "agents";// Agent that handles webhooks for a specific entityexport class WebhookAgent extends Agent { async onRequest(request: Request): Promise<Response> { if (request.method !== "POST") { return new Response("Method not allowed", { status: 405 }); } // Verify the webhook signature const signature = request.headers.get("X-Hub-Signature-256"); const body = await request.text(); if ( !(await this.verifySignature(body, signature, this.env.WEBHOOK_SECRET)) ) { return new Response("Invalid signature", { status: 401 }); } // Process the webhook payload const payload = JSON.parse(body); await this.processEvent(payload); return new Response("OK", { status: 200 }); } private async verifySignature( payload: string, signature: string | null, secret: string, ): Promise<boolean> { if (!signature) return false; const encoder = new TextEncoder(); const key = await crypto.subtle.importKey( "raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"], ); const signatureBytes = await crypto.subtle.sign( "HMAC", key, encoder.encode(payload), ); const expected = `sha256=${Array.from(new Uint8Array(signatureBytes)) .map((b) => b.toString(16).padStart(2, "0")) .join("")}`; return signature === expected; } private async processEvent(payload: unknown) { // Store event, update state, trigger actions... }}// Route webhooks to the right agent instanceexport default { async fetch(request: Request, env: Env): Promise<Response> { const url = new URL(request.url); // Webhook endpoint: POST /webhooks/:entityId if (url.pathname.startsWith("/webhooks/") && request.method === "POST") { const entityId = url.pathname.split("/")[2]; const agent = await getAgentByName(env.WebhookAgent, entityId); return agent.fetch(request); } // Default routing for WebSocket connections return ( (await routeAgentRequest(request, env)) || new Response("Not found", { status: 404 }) ); },} satisfies ExportedHandler<Env>;





Use cases


Webhooks combined with agents enable patterns where each external entity gets its own isolated, stateful agent instance.


Developer tools



Use caseDescription
GitHub Repo MonitorOne agent per repository tracking commits, PRs, issues, and stars
CI/CD Pipeline AgentReact to build/deploy events, notify on failures, track deployment history
Linear/Jira TrackerAuto-triage issues, assign based on content, track resolution times




E-commerce and payments



Use caseDescription
Stripe Customer AgentOne agent per customer tracking payments, subscriptions, and disputes
Shopify Order AgentOrder lifecycle from creation to fulfillment with inventory sync
Payment ReconciliationMatch webhook events to internal records, flag discrepancies




Communication and notifications



Use caseDescription
Twilio SMS/VoiceConversational agents triggered by inbound messages or calls
Slack BotRespond to slash commands, button clicks, and interactive messages
Email TrackingSendGrid/Mailgun delivery events, bounce handling, engagement analytics




IoT and infrastructure



Use caseDescription
Device TelemetryOne agent per device processing sensor data streams
Alert AggregationCollect alerts from PagerDuty, Datadog, or custom monitoring
Home AutomationReact to IFTTT/Zapier triggers with persistent state




SaaS integrations



Use caseDescription
CRM SyncSalesforce/HubSpot contact and deal updates
Calendar AgentGoogle Calendar event notifications and scheduling
Form SubmissionsTypeform, Tally, or custom form webhooks with follow-up actions




Routing webhooks to agents


The key pattern is extracting an entity identifier from the webhook and using getAgentByName() to route to a dedicated agent instance.


Extract entity from payload


Most webhooks include an identifier in the payload:






export default { async fetch(request, env) { if (request.method === "POST" && url.pathname === "/webhooks/github") { const payload = await request.clone().json(); // Extract entity ID from payload const repoFullName = payload.repository?.full_name; if (!repoFullName) { return new Response("Missing repository", { status: 400 }); } // Sanitize for use as agent name const agentName = repoFullName.toLowerCase().replace(/\//g, "-"); // Route to dedicated agent const agent = await getAgentByName(env.RepoAgent, agentName); return agent.fetch(request); } },};

export default { async fetch(request: Request, env: Env): Promise<Response> { if (request.method === "POST" && url.pathname === "/webhooks/github") { const payload = await request.clone().json(); // Extract entity ID from payload const repoFullName = payload.repository?.full_name; if (!repoFullName) { return new Response("Missing repository", { status: 400 }); } // Sanitize for use as agent name const agentName = repoFullName.toLowerCase().replace(/\//g, "-"); // Route to dedicated agent const agent = await getAgentByName(env.RepoAgent, agentName); return agent.fetch(request); } },} satisfies ExportedHandler<Env>;





Extract entity from URL


Alternatively, include the entity ID in the webhook URL:






// Webhook URL: https://your-worker.dev/webhooks/stripe/cus_123456if (url.pathname.startsWith("/webhooks/stripe/")) { const customerId = url.pathname.split("/")[3]; // "cus_123456" const agent = await getAgentByName(env.StripeAgent, customerId); return agent.fetch(request);}

// Webhook URL: https://your-worker.dev/webhooks/stripe/cus_123456if (url.pathname.startsWith("/webhooks/stripe/")) { const customerId = url.pathname.split("/")[3]; // "cus_123456" const agent = await getAgentByName(env.StripeAgent, customerId); return agent.fetch(request);}





Extract entity from headers


Some services include identifiers in headers:






// Slack sends workspace info in headersconst teamId = request.headers.get("X-Slack-Team-Id");if (teamId) { const agent = await getAgentByName(env.SlackAgent, teamId); return agent.fetch(request);}

// Slack sends workspace info in headersconst teamId = request.headers.get("X-Slack-Team-Id");if (teamId) { const agent = await getAgentByName(env.SlackAgent, teamId); return agent.fetch(request);}





Signature verification


Always verify webhook signatures to ensure requests are authentic. Most providers use HMAC-SHA256.


HMAC-SHA256 pattern







async function verifySignature(payload, signature, secret) { if (!signature) return false; const encoder = new TextEncoder(); const key = await crypto.subtle.importKey( "raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"], ); const signatureBytes = await crypto.subtle.sign( "HMAC", key, encoder.encode(payload), ); const expected = `sha256=${Array.from(new Uint8Array(signatureBytes)) .map((b) => b.toString(16).padStart(2, "0")) .join("")}`; // Use timing-safe comparison in production return signature === expected;}

async function verifySignature( payload: string, signature: string | null, secret: string,): Promise<boolean> { if (!signature) return false; const encoder = new TextEncoder(); const key = await crypto.subtle.importKey( "raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"], ); const signatureBytes = await crypto.subtle.sign( "HMAC", key, encoder.encode(payload), ); const expected = `sha256=${Array.from(new Uint8Array(signatureBytes)) .map((b) => b.toString(16).padStart(2, "0")) .join("")}`; // Use timing-safe comparison in production return signature === expected;}





Provider-specific headers



ProviderSignature HeaderAlgorithm
GitHubX-Hub-Signature-256HMAC-SHA256
StripeStripe-SignatureHMAC-SHA256 (with timestamp)
TwilioX-Twilio-SignatureHMAC-SHA1
SlackX-Slack-SignatureHMAC-SHA256 (with timestamp)
ShopifyX-Shopify-Hmac-Sha256HMAC-SHA256 (base64)




Processing webhooks



The onRequest handler


Use onRequest() to handle incoming webhooks in your agent:






export class WebhookAgent extends Agent { async onRequest(request) { // 1. Validate method if (request.method !== "POST") { return new Response("Method not allowed", { status: 405 }); } // 2. Get event type from headers const eventType = request.headers.get("X-Event-Type"); // 3. Verify signature const signature = request.headers.get("X-Signature"); const body = await
…(内容过长已截断)

------
导航页 打开网址