自带 OAuth 应用时如何注册 Composio ingress URL 让实时触发器收到事件【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio如果你用的是 Composio 托管的 OAuth可以直接跳过这篇——ingress 已经配好创建触发器后事件就会流动。本文针对另一种情况你自带BYO自己的 OAuth 应用且目标触发器类型是实时realtime触发器。有些 provider 只把事件推送到你在 OAuth 应用上注册过的 URL所以要把 Composio 的 ingress URL 注册到该 OAuth 应用里一次事件才能进入 Composio。判断标准是触发器类型的requires_webhook_endpoint_setup标志为true只有这种触发器需要做这一步。每个你自带的 OAuth 应用在一个项目内拥有自己的 ingress URLhttps://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event其中{toolkit_slug}是工具包标识{we_xxx}是 webhook endpoint 的 ID。注意一条硬性约束一个 OAuth 应用最多服务一个 Composio 项目——provider 只接受每个 OAuth 应用一个 callback URL每个 ingress URL 也只路由到单个项目。如果同一个 OAuth 应用被多个项目共用先合并到单个项目或按项目分别注册 OAuth 应用再继续。每个项目因此成为独立的 webhook 租户拥有自己的 ingress 速率限制与背压预算、项目范围内的凭据签名密钥和 app-level token 只存储在该项目、事件只扇出到该项目触发器实例的干净投递路径以及按项目计量的能力。所有入站事件在触发任何触发器之前都会在 ingress 做签名校验Slack 使用 HMAC-SHA256其他 provider 使用 Ed25519 或共享 token 匹配provider 对请求时间戳签名时超出允许偏移窗口的请求会被拒绝未签名或被篡改的请求在 ingress 以400拒绝。准备条件一个 Composio API key用于请求头x-api-key你在 provider 侧自建 OAuth 应用的client_id该 OAuth 应用只绑定一个 Composio 项目用户在 Composio 中有该 toolkit 的 connected account创建触发器时需要见 Authentication各 provider 应用后台的凭据如 Slack 的 Signing Secret具体要哪些以 Step 1 返回的setup_fields为准。下文以 Slack 为例完整参考 Webhook Endpoints API各 toolkit 特有的设置说明见其 FAQ 部分例如 Slack。Step 1: 查询 endpoint 需要哪些凭据对目标 toolkit 调用 schema 端点。响应里的setup_fields精确告诉你需要从 provider 应用后台收集哪些字段curl https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slugslack \ -H x-api-key: YOUR_COMPOSIO_API_KEY文档示例的响应{ toolkit_slug: slack, setup_fields: { webhook_signing_secret: { display_name: Signing Secret, description: Webhook request signing secret from your Slack app dashboard, is_required: true, is_secret: true }, app_token: { display_name: App-Level Token, description: Slack xapp- token with authorizations:read scope for event authorization, is_required: true, is_secret: true } } }以 Slack 为例这两个凭据的来源是Signing secret 在 Slack app → Basic Information → App Credentials → Signing SecretApp-level token 在 Slack app → Basic Information → App-Level Tokens需要authorizations:readscope直接消息、私有频道和 reaction 事件需要它只处理公开频道事件时省略。Step 2: 创建 endpoint拿到 ingress URL用toolkit_slug和 OAuth 应用的client_id创建 endpointYOUR_OAUTH_CLIENT_ID换成你 OAuth 应用的 client IDcurl -X POST https://backend.composio.dev/api/v3.1/webhook_endpoints \ -H x-api-key: YOUR_COMPOSIO_API_KEY \ -H Content-Type: application/json \ -d { toolkit_slug: slack, client_id: YOUR_OAUTH_CLIENT_ID }文档示例的响应{ id: we_abc123, toolkit_slug: slack, client_id: YOUR_OAUTH_CLIENT_ID, webhook_url: https://backend.composio.dev/api/v3.1/webhook_ingress/slack/we_abc123/trigger_event, data: null, created_at: 2026-04-24T10:00:00.000Z }保留响应中的两个值id下文记为ENDPOINT_ID如示例中的we_abc123和webhook_urlStep 4 要粘贴进 provider 应用后台。这个调用在同一项目内对(toolkit_slug, client_id)组合是幂等的用同一对参数再次调用会返回已存在的 endpoint不会轮换 URL 也不会清掉已存的 secret。Step 3: 存好 schema 要求的凭据把 Step 1 schema 返回的所有字段放在一个PATCH请求里提交。对 Slack 就是 signing secret 和需要时app-level token 一起提交SIGNING_SECRET换成 provider 后台的签名密钥xapp-...换成你的 app-level tokencurl -X PATCH https://backend.composio.dev/api/v3.1/webhook_endpoints/ENDPOINT_ID \ -H x-api-key: YOUR_COMPOSIO_API_KEY \ -H Content-Type: application/json \ -d { data: { webhook_signing_secret: SIGNING_SECRET, app_token: xapp-... } }**必须在 Step 4 切换 provider 的 callback URL 之前完成这一步。**如果 provider 向 URL 发请求而 endpoint 上还没有 secret每个请求都会以400失败并且 provider 可能在连续失败一段时间窗口后自动禁用该 endpointSlack 约为 36 小时。Step 4: 在 provider 应用后台注册 ingress URL把 Step 2 响应里的webhook_url粘贴到 provider 的应用后台Slack→ Event Subscriptions → Request URLNotion→ Webhook Endpoints在集成设置中对于保存时会发起验证 challenge 的 providerSlack 的url_verification、Notion 的 verification token 等Composio 会自动应答你这边不需要写任何握手代码。provider 接受该 URL 后就可以去 创建触发器。验证注册是否生效文档给出的确认与失败信号如下provider 侧保存 URL 时的验证 challenge 被自动应答、provider 接受 URL说明 ingress 侧就绪用GET查看单个 endpoint确认其状态与已存凭据curl https://backend.composio.dev/api/v3.1/webhook_endpoints/ENDPOINT_ID \ -H x-api-key: YOUR_COMPOSIO_API_KEY列出当前项目全部 endpointcurl https://backend.composio.dev/api/v3.1/webhook_endpoints \ -H x-api-key: YOUR_COMPOSIO_API_KEY反向信号如果 provider 开始向 URL 发事件而 endpoint 尚未存 secret请求会全部以400失败——这正是 Step 3 要先于 Step 4 的原因。URL 被接受后事件链路是provider → ingress URL → 触发器 → 你的订阅或 webhook URL。触发器创建要求用户已有该 toolkit 的 connected account只需传user_idComposio 自动解析连接。例如用 SDK 创建from composio import Composio composio Composio() user_id user-id-123435 # 用户必须先有该 toolkit 的 connected account先完成认证。 trigger composio.triggers.create( slugGITHUB_COMMIT_EVENT, user_iduser_id, trigger_config{owner: your-repo-owner, repo: your-repo-name}, ) print(fTrigger created: {trigger.trigger_id})触发器激活后事件开始流动本地开发可以用subscribe()快速看事件或推荐用 CLIcomposio dev triggers listen --forward http://localhost:8000/webhooks/composio把事件签名后转发到你的本地 handler生产环境用composio.triggers.set_webhook_subscription(webhook_url...)注册项目级 webhook URLhandler 里用parse()验签并解析。细节见 Receiving events 和 Triggers。更新与维护 endpoint轮换 signing secret 或改单个字段PATCH该字段其他字段保留curl -X PATCH https://backend.composio.dev/api/v3.1/webhook_endpoints/ENDPOINT_ID \ -H x-api-key: YOUR_COMPOSIO_API_KEY \ -H Content-Type: application/json \ -d { data: { webhook_signing_secret: NEW_SECRET } }整体替换data没包含的字段会被清空对同一 URL 发POSTcurl -X POST https://backend.composio.dev/api/v3.1/webhook_endpoints/ENDPOINT_ID \ -H x-api-key: YOUR_COMPOSIO_API_KEY \ -H Content-Type: application/json \ -d { data: { webhook_signing_secret: NEW_SECRET, app_token: NEW_APP_TOKEN } }webhook_url在 endpoint 生命周期内不可变provider 侧轮换 signing secret 是对现有 endpoint 的PATCH不要创建新 endpoint。相关文档Custom OAuth webhooks、Webhook Endpoints API、Creating triggers、Receiving events。【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考