Kortix 怎么配置 webhook 触发器并用 HMAC 签名校验外部回调【免费下载链接】agentpressThe open-source AI Management System项目地址: https://gitcode.com/GitHub_Trending/ag/agentpress在 Kortix 里webhook 触发器让外部服务通过一次签名请求直接启动一个 agent sessionKortix 用你事先存入的签名密钥对每个入站请求做 HMAC 校验通过后才带着请求体发起会话。完成本文后你会拥有一个带签名校验的POST /v1/webhooks/projects/project-id/slug端点并能用 HTTP 状态码判断请求是否真的触发了 session。前提是你已经在本地有一个 Kortix 项目并能使用kortixCLItriggers相关命令的完整列表见 CLI 文档。触发器定义写在项目的kortix.yaml里运行时状态如上次触发时间存在数据库中。第一步配置签名密钥webhook 触发器没有无认证模式——缺少secret_env的 webhook 触发器会被直接拒绝。所以先创建密钥kortix secrets set WEBHOOK_SECRET- kortix secrets delivery WEBHOOK_SECRET broker --consumer connector第一条命令通过标准输入读入密钥值KEY-表示从 stdin 读取不要把值直接拼在命令行里。第二条命令把该密钥设为broker投递、connector消费者。这是 webhook 触发器的硬性要求secret_env指向的密钥必须满足这一投递方式否则请求会返回409。密钥名必须匹配^[A-Z_][A-Z0-9_]{0,63}$且不能以KORTIX_开头该前缀保留给平台值。注意一个顺序问题文档明确要求在创建或更新 webhook 触发器之前配置好签名密钥。另外如果这个密钥之前用的是 sandbox 投递改投递方式后要重新轮换一次值因为已有的 sandbox 可能还保留旧值。密钥本身的存取规则identifier/name、exposure、轮换等见 Secrets 文档。第二步添加 webhook 触发器kortix triggers add new-lead --type webhook \ --secret-env WEBHOOK_SECRET \ --prompt A new lead arrived: {{ body.name }} ({{ body.email }}). Add it to the CRM.--secret-env指定用于签名校验的项目密钥名这里对应第一步的WEBHOOK_SECRET。--prompt是模板字符串会渲染成触发后 session 的第一条消息。webhook 触发可用的变量包括{{ body.* }}请求体按 JSON 解析解析失败时退化为{{ body.raw }}、{{ fired_at }}以及{{ headers.content_type }}、{{ headers.user_agent }}、{{ headers.forwarded_for }}等。缺失的模板值渲染为空字符串不会报错。这条命令只修改本地kortix.yaml。如果你想在 manifest 里手写对应的字段形如# kortix.yaml triggers: - slug: new-lead type: webhook secret_env: WEBHOOK_SECRET prompt: A new lead arrived: {{ body.name }} ({{ body.email }}). Add it to the CRM.可选地加一个filter字段点号路径 → 期望字符串来过滤哪些载荷会触发 session例如body.data.direction: inbound。不匹配的投递会返回200但不启动 session——文档给出的用途是打断循环一个同时上报对话双方的源否则会拿 agent 自己的回复再次触发自己。第三步发布并验证触发器状态kortix ship kortix triggers lskortix ship提交并推送kortix.yaml触发器在落地到项目默认分支后生效。kortix triggers ls列出每个触发器的 slug、状态和上次触发时间用它确认新触发器已出现且处于预期状态。第四步从外部服务发送带 HMAC 签名的请求Kortix 用项目 id 和触发器 slug 拼出 webhook URLPOST /v1/webhooks/projects/project-id/slug签名规则文档定义得很具体请求头带X-Kortix-Signature: sha256hmacsha256前缀可省略或使用 GitHub 兼容的X-Hub-Signature-256hmac是对原始请求体做 HMAC-SHA256 得到的值密钥就是secret_env指向的WEBHOOK_SECRET。Kortix 用常数时间比较校验签名。下面是一个示例请求形态sig需由发送方按上述规则计算后替换project-id/new-lead同理替换为你的实际值curl -X POST https://your-kortix-host/v1/webhooks/projects/project-id/new-lead \ -H Content-Type: application/json \ -H X-Kortix-Signature: sha256sig \ -d {name: Jane, email: janeexample.com}请求体里的字段会进入 prompt 模板上面的示例中{{ body.name }}渲染为Jane。用响应状态码判断结果文档给出的状态码语义就是核对手段状态含义202签名或 token 有效。响应体形如{ status: fired \| queued \| deduped, session_id, ... }200有效但被跳过——项目处于 paused 状态或投递不匹配filter400URL 中的 project ID 或 slug 格式非法401签名和 token 都缺失或错误404触发器不存在、已禁用、不是 webhook 类型或项目未激活409签名密钥缺失、不活跃、不可用或未授权connector消费者响应包含webhook_secret_*码和修复指引500认证通过但 session 启动失败排查思路对应着检查项401先核对发送方是否对原始字节而非重新序列化后的 body做了 HMAC-SHA256、密钥是否与WEBHOOK_SECRET一致409说明第一步的broker投递/connector消费者配置没到位200且没触发时检查项目是否被暂停、filter是否过滤掉了这次投递。可选分支不能做 HMAC 的发送方用静态 token只有当请求没有任何签名头时Kortix 才回退到静态 token 校验把密钥本身作为X-Kortix-Token: secret、Authorization: Bearer secret或Authorization: Basic base64(user:secret)密码部分即 token发送。这是文档为无法对 body 做 HMAC 签名的发送方保留的替代路径主路径仍应优先使用 HMAC 签名。已知限制去重webhook 触发以投递 ID 头为键发送方没传 ID 时以 body 和签名的哈希为键。重复投递返回deduped而不会重复开 session。并发上限每个项目默认最多 3 个触发类 session 同时在准备中超出的触发返回queued仍是202等有槽位释放再运行。超时webhook 触发的处理有 45 秒超时。默认新会话webhook 触发默认每次开一个全新 session 和新分支session_mode: fresh如需复用或按键归并 session用kortix triggers set的--session-mode/--session-key调整详见 Triggers 文档 的 Session strategy 一节。暂停项目级kortix triggers pause会让入站 webhook 返回200{ status: skipped }不启动 session同一仓库跑在两个控制面如 dev 和 prod时用它防止重复触发。触发器通过 CLI/API/SDK/仪表盘创建时是直接写默认分支的不走 change request只有改kortix.yaml后kortix ship的路径走正常的分支与 CR 流程——本文的主路径属于后者。【免费下载链接】agentpressThe open-source AI Management System项目地址: https://gitcode.com/GitHub_Trending/ag/agentpress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Kortix 怎么配置 webhook 触发器并用 HMAC 签名校验外部回调
Kortix 怎么配置 webhook 触发器并用 HMAC 签名校验外部回调【免费下载链接】agentpressThe open-source AI Management System项目地址: https://gitcode.com/GitHub_Trending/ag/agentpress在 Kortix 里webhook 触发器让外部服务通过一次签名请求直接启动一个 agent sessionKortix 用你事先存入的签名密钥对每个入站请求做 HMAC 校验通过后才带着请求体发起会话。完成本文后你会拥有一个带签名校验的POST /v1/webhooks/projects/project-id/slug端点并能用 HTTP 状态码判断请求是否真的触发了 session。前提是你已经在本地有一个 Kortix 项目并能使用kortixCLItriggers相关命令的完整列表见 CLI 文档。触发器定义写在项目的kortix.yaml里运行时状态如上次触发时间存在数据库中。第一步配置签名密钥webhook 触发器没有无认证模式——缺少secret_env的 webhook 触发器会被直接拒绝。所以先创建密钥kortix secrets set WEBHOOK_SECRET- kortix secrets delivery WEBHOOK_SECRET broker --consumer connector第一条命令通过标准输入读入密钥值KEY-表示从 stdin 读取不要把值直接拼在命令行里。第二条命令把该密钥设为broker投递、connector消费者。这是 webhook 触发器的硬性要求secret_env指向的密钥必须满足这一投递方式否则请求会返回409。密钥名必须匹配^[A-Z_][A-Z0-9_]{0,63}$且不能以KORTIX_开头该前缀保留给平台值。注意一个顺序问题文档明确要求在创建或更新 webhook 触发器之前配置好签名密钥。另外如果这个密钥之前用的是 sandbox 投递改投递方式后要重新轮换一次值因为已有的 sandbox 可能还保留旧值。密钥本身的存取规则identifier/name、exposure、轮换等见 Secrets 文档。第二步添加 webhook 触发器kortix triggers add new-lead --type webhook \ --secret-env WEBHOOK_SECRET \ --prompt A new lead arrived: {{ body.name }} ({{ body.email }}). Add it to the CRM.--secret-env指定用于签名校验的项目密钥名这里对应第一步的WEBHOOK_SECRET。--prompt是模板字符串会渲染成触发后 session 的第一条消息。webhook 触发可用的变量包括{{ body.* }}请求体按 JSON 解析解析失败时退化为{{ body.raw }}、{{ fired_at }}以及{{ headers.content_type }}、{{ headers.user_agent }}、{{ headers.forwarded_for }}等。缺失的模板值渲染为空字符串不会报错。这条命令只修改本地kortix.yaml。如果你想在 manifest 里手写对应的字段形如# kortix.yaml triggers: - slug: new-lead type: webhook secret_env: WEBHOOK_SECRET prompt: A new lead arrived: {{ body.name }} ({{ body.email }}). Add it to the CRM.可选地加一个filter字段点号路径 → 期望字符串来过滤哪些载荷会触发 session例如body.data.direction: inbound。不匹配的投递会返回200但不启动 session——文档给出的用途是打断循环一个同时上报对话双方的源否则会拿 agent 自己的回复再次触发自己。第三步发布并验证触发器状态kortix ship kortix triggers lskortix ship提交并推送kortix.yaml触发器在落地到项目默认分支后生效。kortix triggers ls列出每个触发器的 slug、状态和上次触发时间用它确认新触发器已出现且处于预期状态。第四步从外部服务发送带 HMAC 签名的请求Kortix 用项目 id 和触发器 slug 拼出 webhook URLPOST /v1/webhooks/projects/project-id/slug签名规则文档定义得很具体请求头带X-Kortix-Signature: sha256hmacsha256前缀可省略或使用 GitHub 兼容的X-Hub-Signature-256hmac是对原始请求体做 HMAC-SHA256 得到的值密钥就是secret_env指向的WEBHOOK_SECRET。Kortix 用常数时间比较校验签名。下面是一个示例请求形态sig需由发送方按上述规则计算后替换project-id/new-lead同理替换为你的实际值curl -X POST https://your-kortix-host/v1/webhooks/projects/project-id/new-lead \ -H Content-Type: application/json \ -H X-Kortix-Signature: sha256sig \ -d {name: Jane, email: janeexample.com}请求体里的字段会进入 prompt 模板上面的示例中{{ body.name }}渲染为Jane。用响应状态码判断结果文档给出的状态码语义就是核对手段状态含义202签名或 token 有效。响应体形如{ status: fired \| queued \| deduped, session_id, ... }200有效但被跳过——项目处于 paused 状态或投递不匹配filter400URL 中的 project ID 或 slug 格式非法401签名和 token 都缺失或错误404触发器不存在、已禁用、不是 webhook 类型或项目未激活409签名密钥缺失、不活跃、不可用或未授权connector消费者响应包含webhook_secret_*码和修复指引500认证通过但 session 启动失败排查思路对应着检查项401先核对发送方是否对原始字节而非重新序列化后的 body做了 HMAC-SHA256、密钥是否与WEBHOOK_SECRET一致409说明第一步的broker投递/connector消费者配置没到位200且没触发时检查项目是否被暂停、filter是否过滤掉了这次投递。可选分支不能做 HMAC 的发送方用静态 token只有当请求没有任何签名头时Kortix 才回退到静态 token 校验把密钥本身作为X-Kortix-Token: secret、Authorization: Bearer secret或Authorization: Basic base64(user:secret)密码部分即 token发送。这是文档为无法对 body 做 HMAC 签名的发送方保留的替代路径主路径仍应优先使用 HMAC 签名。已知限制去重webhook 触发以投递 ID 头为键发送方没传 ID 时以 body 和签名的哈希为键。重复投递返回deduped而不会重复开 session。并发上限每个项目默认最多 3 个触发类 session 同时在准备中超出的触发返回queued仍是202等有槽位释放再运行。超时webhook 触发的处理有 45 秒超时。默认新会话webhook 触发默认每次开一个全新 session 和新分支session_mode: fresh如需复用或按键归并 session用kortix triggers set的--session-mode/--session-key调整详见 Triggers 文档 的 Session strategy 一节。暂停项目级kortix triggers pause会让入站 webhook 返回200{ status: skipped }不启动 session同一仓库跑在两个控制面如 dev 和 prod时用它防止重复触发。触发器通过 CLI/API/SDK/仪表盘创建时是直接写默认分支的不走 change request只有改kortix.yaml后kortix ship的路径走正常的分支与 CR 流程——本文的主路径属于后者。【免费下载链接】agentpressThe open-source AI Management System项目地址: https://gitcode.com/GitHub_Trending/ag/agentpress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考