@cursor/bdk 0.2.13 → 0.2.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (322) hide show
  1. package/AGENTS.md +51 -52
  2. package/README.md +1 -1
  3. package/dist/bin/agent-sdk.js +0 -0
  4. package/dist/bin/agent-serve.js +0 -0
  5. package/dist/channels/slack/attachments.d.ts +2 -0
  6. package/dist/channels/slack/attachments.d.ts.map +1 -1
  7. package/dist/channels/slack/attachments.js +17 -5
  8. package/dist/channels/slack/channel-watch.d.ts +4 -2
  9. package/dist/channels/slack/channel-watch.d.ts.map +1 -1
  10. package/dist/channels/slack/channel-watch.js +4 -2
  11. package/dist/channels/slack/slack-channel.d.ts.map +1 -1
  12. package/dist/channels/slack/slack-channel.js +4 -2
  13. package/dist/channels/slack/types.d.ts +6 -4
  14. package/dist/channels/slack/types.d.ts.map +1 -1
  15. package/dist/connections.d.ts +29 -0
  16. package/dist/connections.d.ts.map +1 -1
  17. package/dist/connections.js +54 -0
  18. package/dist/docs/404.html +2 -2
  19. package/dist/docs/assets/{app.CaLG1pPt.js → app.CRMxF0qX.js} +4 -4
  20. package/dist/docs/assets/{building-with-agents.md.Df87rAe1.js → building-with-agents.md.Bi9CQ-bR.js} +3 -3
  21. package/dist/docs/assets/{building-with-agents.md.Df87rAe1.lean.js → building-with-agents.md.Bi9CQ-bR.lean.js} +1 -1
  22. package/dist/docs/assets/chunks/@localSearchIndexroot.BZwvb2LN.js +1 -0
  23. package/dist/docs/assets/chunks/{VPLocalSearchBox.YsP_2wqD.js → VPLocalSearchBox.C4BiQe53.js} +1 -1
  24. package/dist/docs/assets/chunks/{arc.C2j9hR7c.js → arc.D1TA2Mxn.js} +1 -1
  25. package/dist/docs/assets/chunks/{architectureDiagram-Q4EWVU46.C5qkGp7y.js → architectureDiagram-Q4EWVU46.CA-hBJCN.js} +1 -1
  26. package/dist/docs/assets/chunks/{baseUniq.U6GgTHOD.js → baseUniq.CzsSgiab.js} +1 -1
  27. package/dist/docs/assets/chunks/{blockDiagram-DXYQGD6D.D51mJop2.js → blockDiagram-DXYQGD6D.sxrH_f0l.js} +1 -1
  28. package/dist/docs/assets/chunks/{c4Diagram-AHTNJAMY.w1d6QxV7.js → c4Diagram-AHTNJAMY.D_Z3mqAl.js} +1 -1
  29. package/dist/docs/assets/chunks/channel.D7DtboxW.js +1 -0
  30. package/dist/docs/assets/chunks/{chunk-4BX2VUAB.B_A815un.js → chunk-4BX2VUAB.BS6_uTUf.js} +1 -1
  31. package/dist/docs/assets/chunks/{chunk-4TB4RGXK.DMrm-ZCb.js → chunk-4TB4RGXK.D-URAeTU.js} +1 -1
  32. package/dist/docs/assets/chunks/{chunk-55IACEB6.8qw6Xdal.js → chunk-55IACEB6.b4SZc5kO.js} +1 -1
  33. package/dist/docs/assets/chunks/{chunk-EDXVE4YY.Cq_nHODn.js → chunk-EDXVE4YY.DLKEEDkN.js} +1 -1
  34. package/dist/docs/assets/chunks/{chunk-FMBD7UC4.B67ohCYn.js → chunk-FMBD7UC4.3SyQHgpY.js} +1 -1
  35. package/dist/docs/assets/chunks/{chunk-OYMX7WX6.Bo8rQI8F.js → chunk-OYMX7WX6.DBKKaFeS.js} +1 -1
  36. package/dist/docs/assets/chunks/{chunk-QZHKN3VN.BERUMfE9.js → chunk-QZHKN3VN.BhCYeR7H.js} +1 -1
  37. package/dist/docs/assets/chunks/{chunk-YZCP3GAM.DWG2tXIX.js → chunk-YZCP3GAM.Cpg0VgI7.js} +1 -1
  38. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.irslOV8B.js +1 -0
  39. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.irslOV8B.js +1 -0
  40. package/dist/docs/assets/chunks/clone.DosLeDYL.js +1 -0
  41. package/dist/docs/assets/chunks/{cose-bilkent-S5V4N54A.tezXBs9b.js → cose-bilkent-S5V4N54A.4q0YNZN6.js} +1 -1
  42. package/dist/docs/assets/chunks/{dagre-KV5264BT.aSbEUwT7.js → dagre-KV5264BT.Bk_CcQPr.js} +1 -1
  43. package/dist/docs/assets/chunks/{diagram-5BDNPKRD.vnT6aJ57.js → diagram-5BDNPKRD.CgreoM_Z.js} +1 -1
  44. package/dist/docs/assets/chunks/{diagram-G4DWMVQ6.hGYdrDa2.js → diagram-G4DWMVQ6.DlZGpm6W.js} +1 -1
  45. package/dist/docs/assets/chunks/{diagram-MMDJMWI5.CmdSUP6L.js → diagram-MMDJMWI5.BxtXxgIR.js} +1 -1
  46. package/dist/docs/assets/chunks/{diagram-TYMM5635.BbAnLEBB.js → diagram-TYMM5635.DSzlJp2D.js} +1 -1
  47. package/dist/docs/assets/chunks/{erDiagram-SMLLAGMA.H40W4HWE.js → erDiagram-SMLLAGMA.BN1YUmEV.js} +1 -1
  48. package/dist/docs/assets/chunks/{flowDiagram-DWJPFMVM.BFMtUSv-.js → flowDiagram-DWJPFMVM.B61NGNYu.js} +1 -1
  49. package/dist/docs/assets/chunks/{ganttDiagram-T4ZO3ILL.CbYiu7Dt.js → ganttDiagram-T4ZO3ILL.DR-tto3M.js} +1 -1
  50. package/dist/docs/assets/chunks/{gitGraphDiagram-UUTBAWPF.Cyc5mzZD.js → gitGraphDiagram-UUTBAWPF.CBPs2W_2.js} +1 -1
  51. package/dist/docs/assets/chunks/{graph.BRptDG1H.js → graph.DmlaqzCE.js} +1 -1
  52. package/dist/docs/assets/chunks/{infoDiagram-42DDH7IO.Bz6KCA3a.js → infoDiagram-42DDH7IO.obPv-fFg.js} +1 -1
  53. package/dist/docs/assets/chunks/{ishikawaDiagram-UXIWVN3A.DDJ_7_Fq.js → ishikawaDiagram-UXIWVN3A.CXHTUcM3.js} +1 -1
  54. package/dist/docs/assets/chunks/{journeyDiagram-VCZTEJTY.D0t_ltlb.js → journeyDiagram-VCZTEJTY.BoVHerYZ.js} +1 -1
  55. package/dist/docs/assets/chunks/{kanban-definition-6JOO6SKY.DyyNsMfi.js → kanban-definition-6JOO6SKY.CfYmPHZg.js} +1 -1
  56. package/dist/docs/assets/chunks/{layout.Cbxq-Rhp.js → layout.621UdAhB.js} +1 -1
  57. package/dist/docs/assets/chunks/{linear.DxGYL0MP.js → linear.Cz_zRKjr.js} +1 -1
  58. package/dist/docs/assets/chunks/{min.DA5KL8wu.js → min.ON4GjCH7.js} +1 -1
  59. package/dist/docs/assets/chunks/{mindmap-definition-QFDTVHPH.Bc72Utls.js → mindmap-definition-QFDTVHPH.DLPMLJlv.js} +1 -1
  60. package/dist/docs/assets/chunks/{pieDiagram-DEJITSTG.BtpHnIB_.js → pieDiagram-DEJITSTG.BFp11AYt.js} +1 -1
  61. package/dist/docs/assets/chunks/{quadrantDiagram-34T5L4WZ.Cx4oCSRR.js → quadrantDiagram-34T5L4WZ.ChX7xo6B.js} +1 -1
  62. package/dist/docs/assets/chunks/{requirementDiagram-MS252O5E.BC0hXWlW.js → requirementDiagram-MS252O5E.DbKtHG_Q.js} +1 -1
  63. package/dist/docs/assets/chunks/{sankeyDiagram-XADWPNL6.Dg8T1SEp.js → sankeyDiagram-XADWPNL6.Spw8tv-7.js} +1 -1
  64. package/dist/docs/assets/chunks/{sequenceDiagram-FGHM5R23.CWSdHYAF.js → sequenceDiagram-FGHM5R23.BYso9LlE.js} +1 -1
  65. package/dist/docs/assets/chunks/{stateDiagram-FHFEXIEX.0MVPRI28.js → stateDiagram-FHFEXIEX.D8l54jqW.js} +1 -1
  66. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.CAYMmzGj.js +1 -0
  67. package/dist/docs/assets/chunks/{theme.DO1avLBn.js → theme.m_Ethbkv.js} +2 -2
  68. package/dist/docs/assets/chunks/{timeline-definition-GMOUNBTQ.BuRinAVi.js → timeline-definition-GMOUNBTQ.BLdhhyy9.js} +1 -1
  69. package/dist/docs/assets/chunks/{vennDiagram-DHZGUBPP.DXf0PCoJ.js → vennDiagram-DHZGUBPP.CyGT2F_P.js} +1 -1
  70. package/dist/docs/assets/chunks/wardley-RL74JXVD.C5JJS3bh.js +162 -0
  71. package/dist/docs/assets/chunks/{wardleyDiagram-NUSXRM2D.T4ThngYV.js → wardleyDiagram-NUSXRM2D.p_Sz9p1i.js} +1 -1
  72. package/dist/docs/assets/chunks/{xychartDiagram-5P7HB3ND.b4pZF3D5.js → xychartDiagram-5P7HB3ND.DtXsNUaf.js} +1 -1
  73. package/dist/docs/assets/deployment.md.hKKN9I4c.js +31 -0
  74. package/dist/docs/assets/{deployment.md.BYuEcDBv.lean.js → deployment.md.hKKN9I4c.lean.js} +1 -1
  75. package/dist/docs/assets/{evals.md.C851kViu.js → evals.md.CHR34K1Y.js} +3 -7
  76. package/dist/docs/assets/{evals.md.C851kViu.lean.js → evals.md.CHR34K1Y.lean.js} +1 -1
  77. package/dist/docs/assets/guides_cloud-agents.md.CBK7W0-O.js +9 -0
  78. package/dist/docs/assets/guides_cloud-agents.md.CBK7W0-O.lean.js +1 -0
  79. package/dist/docs/assets/guides_grokbot-agents.md.BwAykJ7U.js +15 -0
  80. package/dist/docs/assets/{guides_grokbot-agents.md.tD1smFhU.lean.js → guides_grokbot-agents.md.BwAykJ7U.lean.js} +1 -1
  81. package/dist/docs/assets/{guides_hooks.md.5Ce3NXxZ.js → guides_hooks.md.B_bKG1oA.js} +1 -1
  82. package/dist/docs/assets/{guides_improve.md.CRrYq22s.js → guides_improve.md.CZKVt1cT.js} +2 -3
  83. package/dist/docs/assets/{guides_improve.md.CRrYq22s.lean.js → guides_improve.md.CZKVt1cT.lean.js} +1 -1
  84. package/dist/docs/assets/{guides_mcp-oauth.md.DR3zhC9r.js → guides_mcp-oauth.md.BM_eFC0L.js} +3 -15
  85. package/dist/docs/assets/guides_mcp-oauth.md.BM_eFC0L.lean.js +1 -0
  86. package/dist/docs/assets/{guides_webhooks.md.BBvAm_VF.js → guides_webhooks.md.Cpdc3BDX.js} +13 -12
  87. package/dist/docs/assets/{guides_webhooks.md.BBvAm_VF.lean.js → guides_webhooks.md.Cpdc3BDX.lean.js} +1 -1
  88. package/dist/docs/assets/{index.md.Dxxr7pFa.js → index.md.BIBHIQtU.js} +1 -1
  89. package/dist/docs/assets/{quickstart.md.BK5gjHM2.js → quickstart.md.CduLGBAB.js} +1 -1
  90. package/dist/docs/assets/reference_channels.md.DYg0CLud.js +22 -0
  91. package/dist/docs/assets/{reference_channels.md.LbNIJBwd.lean.js → reference_channels.md.DYg0CLud.lean.js} +1 -1
  92. package/dist/docs/assets/{reference_cli.md.dYCAL2lB.js → reference_cli.md.BYNIHwbi.js} +15 -12
  93. package/dist/docs/assets/{reference_cli.md.dYCAL2lB.lean.js → reference_cli.md.BYNIHwbi.lean.js} +1 -1
  94. package/dist/docs/assets/{reference_connections.md.DLrgAd5f.js → reference_connections.md.CxbLpaaP.js} +4 -5
  95. package/dist/docs/assets/{reference_connections.md.DLrgAd5f.lean.js → reference_connections.md.CxbLpaaP.lean.js} +1 -1
  96. package/dist/docs/assets/{reference_evals.md.D5i8PuXJ.js → reference_evals.md.if--BLd0.js} +1 -1
  97. package/dist/docs/assets/{reference_hooks.md.B-eGa2km.js → reference_hooks.md.DbJC8mcZ.js} +1 -1
  98. package/dist/docs/assets/reference_http-api.md.CrqhTv6S.js +11 -0
  99. package/dist/docs/assets/{reference_http-api.md.DbFNOubV.lean.js → reference_http-api.md.CrqhTv6S.lean.js} +1 -1
  100. package/dist/docs/assets/reference_playground.md.q4MI-0td.js +1 -0
  101. package/dist/docs/assets/reference_playground.md.q4MI-0td.lean.js +1 -0
  102. package/dist/docs/assets/{reference_schedules.md.BuJ8fgMa.js → reference_schedules.md.03Ryy9ca.js} +5 -5
  103. package/dist/docs/assets/{reference_schedules.md.BuJ8fgMa.lean.js → reference_schedules.md.03Ryy9ca.lean.js} +1 -1
  104. package/dist/docs/assets/reference_sessions.md.C_uzIWuy.js +1 -0
  105. package/dist/docs/assets/{reference_skills.md.C0guGcH0.js → reference_skills.md.Ckddg6KX.js} +4 -4
  106. package/dist/docs/assets/{reference_tools.md.DzIY9JzY.js → reference_tools.md.08XR7lIl.js} +3 -14
  107. package/dist/docs/assets/reference_tools.md.08XR7lIl.lean.js +1 -0
  108. package/dist/docs/assets/{templates_grokbot-agents.md.2sydjFiO.js → templates_grokbot-agents.md.DgpPEs7B.js} +1 -1
  109. package/dist/docs/assets/troubleshooting.md.PCafNCb5.js +1 -0
  110. package/dist/docs/assets/{troubleshooting.md.x-GBa7wN.lean.js → troubleshooting.md.PCafNCb5.lean.js} +1 -1
  111. package/dist/docs/building-with-agents.html +37 -37
  112. package/dist/docs/building-with-agents.md +5 -5
  113. package/dist/docs/deployment.html +43 -41
  114. package/dist/docs/deployment.md +70 -33
  115. package/dist/docs/evals.html +38 -42
  116. package/dist/docs/evals.md +1 -16
  117. package/dist/docs/guides/agent-to-agent.html +35 -35
  118. package/dist/docs/guides/bitbucket.html +35 -35
  119. package/dist/docs/guides/cloud-agents.html +38 -39
  120. package/dist/docs/guides/cloud-agents.md +2 -8
  121. package/dist/docs/guides/convert-automation.html +35 -35
  122. package/dist/docs/guides/github.html +35 -35
  123. package/dist/docs/guides/gitlab.html +35 -35
  124. package/dist/docs/guides/grokbot-agents.html +37 -38
  125. package/dist/docs/guides/grokbot-agents.md +9 -13
  126. package/dist/docs/guides/hooks.html +37 -37
  127. package/dist/docs/guides/hooks.md +0 -1
  128. package/dist/docs/guides/improve.html +37 -38
  129. package/dist/docs/guides/improve.md +4 -6
  130. package/dist/docs/guides/jev.html +35 -35
  131. package/dist/docs/guides/mcp-oauth.html +39 -51
  132. package/dist/docs/guides/mcp-oauth.md +17 -40
  133. package/dist/docs/guides/migrate.html +35 -35
  134. package/dist/docs/guides/opentelemetry.html +35 -35
  135. package/dist/docs/guides/slack.html +35 -35
  136. package/dist/docs/guides/webhooks.html +47 -46
  137. package/dist/docs/guides/webhooks.md +35 -18
  138. package/dist/docs/hashmap.json +1 -1
  139. package/dist/docs/hillclimbing.html +35 -35
  140. package/dist/docs/index.html +36 -36
  141. package/dist/docs/index.md +1 -1
  142. package/dist/docs/llms-full.txt +347 -269
  143. package/dist/docs/llms.txt +4 -4
  144. package/dist/docs/quickstart.html +37 -37
  145. package/dist/docs/quickstart.md +2 -2
  146. package/dist/docs/reference/agent-config.html +35 -35
  147. package/dist/docs/reference/artifacts.html +35 -35
  148. package/dist/docs/reference/channels.html +42 -43
  149. package/dist/docs/reference/channels.md +29 -13
  150. package/dist/docs/reference/cli.html +49 -46
  151. package/dist/docs/reference/cli.md +113 -40
  152. package/dist/docs/reference/connections.html +39 -40
  153. package/dist/docs/reference/connections.md +6 -5
  154. package/dist/docs/reference/evals.html +37 -37
  155. package/dist/docs/reference/evals.md +2 -4
  156. package/dist/docs/reference/extensions.html +35 -35
  157. package/dist/docs/reference/hooks.html +37 -37
  158. package/dist/docs/reference/hooks.md +0 -1
  159. package/dist/docs/reference/http-api.html +38 -38
  160. package/dist/docs/reference/http-api.md +7 -17
  161. package/dist/docs/reference/instructions.html +35 -35
  162. package/dist/docs/reference/playground.html +37 -37
  163. package/dist/docs/reference/playground.md +1 -4
  164. package/dist/docs/reference/project-layout.html +35 -35
  165. package/dist/docs/reference/prompt.html +35 -35
  166. package/dist/docs/reference/schedules.html +39 -39
  167. package/dist/docs/reference/schedules.md +26 -3
  168. package/dist/docs/reference/sessions.html +36 -36
  169. package/dist/docs/reference/sessions.md +1 -2
  170. package/dist/docs/reference/skills.html +39 -39
  171. package/dist/docs/reference/skills.md +1 -1
  172. package/dist/docs/reference/subagents.html +35 -35
  173. package/dist/docs/reference/tools.html +39 -50
  174. package/dist/docs/reference/tools.md +2 -28
  175. package/dist/docs/templates/agentic-owners.html +35 -35
  176. package/dist/docs/templates/grokbot-agents.html +37 -37
  177. package/dist/docs/templates/grokbot-agents.md +1 -1
  178. package/dist/docs/templates/security-reviewer.html +35 -35
  179. package/dist/docs/templates/thermo-quality-review.html +35 -35
  180. package/dist/docs/templates/thermo-review.html +35 -35
  181. package/dist/docs/templates/triage.html +35 -35
  182. package/dist/docs/troubleshooting.html +36 -36
  183. package/dist/docs/troubleshooting.md +12 -7
  184. package/dist/executors.d.ts +11 -0
  185. package/dist/executors.d.ts.map +1 -0
  186. package/dist/executors.js +21 -0
  187. package/dist/extensions/cursor-cloud-agents/extension.d.ts +6 -2
  188. package/dist/extensions/cursor-cloud-agents/extension.d.ts.map +1 -1
  189. package/dist/extensions/cursor-cloud-agents/extension.js +5 -1
  190. package/dist/extensions/cursor-cloud-agents/lib/channels.d.ts.map +1 -1
  191. package/dist/extensions/cursor-cloud-agents/lib/channels.js +5 -1
  192. package/dist/extensions/cursor-cloud-agents/lib/launch-agent.d.ts +21 -4
  193. package/dist/extensions/cursor-cloud-agents/lib/launch-agent.d.ts.map +1 -1
  194. package/dist/extensions/cursor-cloud-agents/lib/launch-agent.js +26 -5
  195. package/dist/files.d.ts +1 -0
  196. package/dist/files.d.ts.map +1 -1
  197. package/dist/files.js +3 -1
  198. package/dist/filesystem.d.ts +10 -0
  199. package/dist/filesystem.d.ts.map +1 -1
  200. package/dist/filesystem.js +128 -0
  201. package/dist/index.d.ts +1 -1
  202. package/dist/index.d.ts.map +1 -1
  203. package/dist/index.js +1 -1
  204. package/dist/internal/cli-deploy.d.ts.map +1 -1
  205. package/dist/internal/cli-deploy.js +17 -0
  206. package/dist/internal/continuation-identity.js +1 -1
  207. package/dist/internal/conversation-mirror.d.ts +11 -0
  208. package/dist/internal/conversation-mirror.d.ts.map +1 -1
  209. package/dist/internal/conversation-mirror.js +198 -125
  210. package/dist/internal/conversation-pack.d.ts +29 -0
  211. package/dist/internal/conversation-pack.d.ts.map +1 -0
  212. package/dist/internal/conversation-pack.js +96 -0
  213. package/dist/internal/deploy-client.d.ts +2 -0
  214. package/dist/internal/deploy-client.d.ts.map +1 -1
  215. package/dist/internal/deploy-client.js +4 -0
  216. package/dist/internal/discovery/agent-config.d.ts +6 -0
  217. package/dist/internal/discovery/agent-config.d.ts.map +1 -1
  218. package/dist/internal/discovery/agent-config.js +19 -0
  219. package/dist/internal/discovery/agent.d.ts.map +1 -1
  220. package/dist/internal/discovery/agent.js +2 -1
  221. package/dist/internal/hosted-catch-protocol.d.ts +2 -0
  222. package/dist/internal/hosted-catch-protocol.d.ts.map +1 -1
  223. package/dist/internal/hosted-catch-protocol.js +2 -0
  224. package/dist/internal/hosted-catch.d.ts +2 -3
  225. package/dist/internal/hosted-catch.d.ts.map +1 -1
  226. package/dist/internal/hosted-catch.js +2 -3
  227. package/dist/internal/hosted-delivery.d.ts.map +1 -1
  228. package/dist/internal/hosted-delivery.js +22 -12
  229. package/dist/internal/hosted-execution-flush.d.ts +6 -3
  230. package/dist/internal/hosted-execution-flush.d.ts.map +1 -1
  231. package/dist/internal/hosted-execution-flush.js +28 -31
  232. package/dist/internal/peer-connections.d.ts +6 -2
  233. package/dist/internal/peer-connections.d.ts.map +1 -1
  234. package/dist/internal/peer-connections.js +23 -19
  235. package/dist/internal/sdk-runner.d.ts.map +1 -1
  236. package/dist/internal/sdk-runner.js +13 -2
  237. package/dist/internal/server.d.ts.map +1 -1
  238. package/dist/internal/server.js +6 -5
  239. package/dist/internal/session-engine.d.ts.map +1 -1
  240. package/dist/internal/session-engine.js +4 -0
  241. package/dist/internal/session-run-log.d.ts.map +1 -1
  242. package/dist/internal/session-run-log.js +26 -11
  243. package/dist/internal/turn-cost.d.ts +2 -2
  244. package/dist/internal/turn-cost.d.ts.map +1 -1
  245. package/dist/internal/turn-cost.js +17 -3
  246. package/dist/playground/assets/index-BVYWBxLU.css +1 -0
  247. package/dist/playground/assets/{index-DIiKbZ25.js → index-DCsq6f_I.js} +45 -45
  248. package/dist/playground/index.html +2 -2
  249. package/dist/types.d.ts +18 -0
  250. package/dist/types.d.ts.map +1 -1
  251. package/docs/README.md +1 -1
  252. package/docs/building-with-agents.md +5 -5
  253. package/docs/deployment.md +70 -33
  254. package/docs/evals.md +1 -16
  255. package/docs/guides/cloud-agents.md +3 -9
  256. package/docs/guides/grokbot-agents.md +10 -14
  257. package/docs/guides/hooks.md +0 -1
  258. package/docs/guides/improve.md +4 -6
  259. package/docs/guides/mcp-oauth.md +18 -41
  260. package/docs/guides/webhooks.md +35 -18
  261. package/docs/quickstart.md +2 -2
  262. package/docs/reference/channels.md +29 -13
  263. package/docs/reference/cli.md +113 -40
  264. package/docs/reference/connections.md +6 -5
  265. package/docs/reference/evals.md +2 -4
  266. package/docs/reference/hooks.md +0 -1
  267. package/docs/reference/http-api.md +7 -17
  268. package/docs/reference/playground.md +2 -5
  269. package/docs/reference/schedules.md +26 -3
  270. package/docs/reference/sessions.md +1 -2
  271. package/docs/reference/skills.md +1 -1
  272. package/docs/reference/tools.md +3 -29
  273. package/docs/templates/grokbot-agents.md +1 -1
  274. package/docs/troubleshooting.md +12 -7
  275. package/package.json +43 -32
  276. package/skills/create-agent/SKILL.md +9 -6
  277. package/skills/debug/SKILL.md +3 -4
  278. package/skills/evals/SKILL.md +2 -2
  279. package/skills/framework-map/SKILL.md +10 -10
  280. package/skills/mcp-auth/SKILL.md +10 -34
  281. package/skills/migrate-v2/SKILL.md +13 -9
  282. package/skills/setup-slack/SKILL.md +0 -13
  283. package/templates/agents-md/README.md +3 -3
  284. package/templates/agents-md/bot/channels/queue.ts +3 -8
  285. package/templates/agents-md/bot/instructions.md +1 -2
  286. package/templates/agents-md/bot/tools/apply_agents.ts +0 -1
  287. package/templates/agents-md/evals/agents.eval.ts +2 -2
  288. package/templates/demo/bot/channels/queue.ts +5 -15
  289. package/templates/grokbot-agents/.gitignore +4 -0
  290. package/templates/pr-autofixer/bot/channels/drive.ts +3 -16
  291. package/templates/security-help/.gitignore +4 -0
  292. package/templates/triage/bot/channels/queue.ts +11 -22
  293. package/templates/triage/bot/channels/webhook.ts +3 -6
  294. package/templates/triage/bot/lib/parse-queue-event.ts +0 -6
  295. package/dist/docs/assets/chunks/@localSearchIndexroot.DvlKuIO-.js +0 -1
  296. package/dist/docs/assets/chunks/channel.BRSFxCcD.js +0 -1
  297. package/dist/docs/assets/chunks/classDiagram-6PBFFD2Q.Cmtm6WkN.js +0 -1
  298. package/dist/docs/assets/chunks/classDiagram-v2-HSJHXN6E.Cmtm6WkN.js +0 -1
  299. package/dist/docs/assets/chunks/clone.JMC96Eo6.js +0 -1
  300. package/dist/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.N4Am6sXd.js +0 -1
  301. package/dist/docs/assets/chunks/wardley-RL74JXVD._eATmGtu.js +0 -162
  302. package/dist/docs/assets/deployment.md.BYuEcDBv.js +0 -29
  303. package/dist/docs/assets/guides_cloud-agents.md.CWJjS9No.js +0 -10
  304. package/dist/docs/assets/guides_cloud-agents.md.CWJjS9No.lean.js +0 -1
  305. package/dist/docs/assets/guides_grokbot-agents.md.tD1smFhU.js +0 -16
  306. package/dist/docs/assets/guides_mcp-oauth.md.DR3zhC9r.lean.js +0 -1
  307. package/dist/docs/assets/reference_channels.md.LbNIJBwd.js +0 -23
  308. package/dist/docs/assets/reference_http-api.md.DbFNOubV.js +0 -11
  309. package/dist/docs/assets/reference_playground.md.1hx0gcIu.js +0 -1
  310. package/dist/docs/assets/reference_playground.md.1hx0gcIu.lean.js +0 -1
  311. package/dist/docs/assets/reference_sessions.md.CyM7ARz1.js +0 -1
  312. package/dist/docs/assets/reference_tools.md.DzIY9JzY.lean.js +0 -1
  313. package/dist/docs/assets/troubleshooting.md.x-GBa7wN.js +0 -1
  314. package/dist/playground/assets/index-CzttDc-d.css +0 -1
  315. /package/dist/docs/assets/{guides_hooks.md.5Ce3NXxZ.lean.js → guides_hooks.md.B_bKG1oA.lean.js} +0 -0
  316. /package/dist/docs/assets/{index.md.Dxxr7pFa.lean.js → index.md.BIBHIQtU.lean.js} +0 -0
  317. /package/dist/docs/assets/{quickstart.md.BK5gjHM2.lean.js → quickstart.md.CduLGBAB.lean.js} +0 -0
  318. /package/dist/docs/assets/{reference_evals.md.D5i8PuXJ.lean.js → reference_evals.md.if--BLd0.lean.js} +0 -0
  319. /package/dist/docs/assets/{reference_hooks.md.B-eGa2km.lean.js → reference_hooks.md.DbJC8mcZ.lean.js} +0 -0
  320. /package/dist/docs/assets/{reference_sessions.md.CyM7ARz1.lean.js → reference_sessions.md.C_uzIWuy.lean.js} +0 -0
  321. /package/dist/docs/assets/{reference_skills.md.C0guGcH0.lean.js → reference_skills.md.Ckddg6KX.lean.js} +0 -0
  322. /package/dist/docs/assets/{templates_grokbot-agents.md.2sydjFiO.lean.js → templates_grokbot-agents.md.DgpPEs7B.lean.js} +0 -0
package/dist/docs/guides/webhooks.html CHANGED
@@ -9,51 +9,51 @@
9
9
  <link rel="preload stylesheet" href="/docs/assets/style.Dwls12uf.css" as="style">
10
10
  <link rel="preload stylesheet" href="/docs/vp-icons.css" as="style">
11
11
 
12
- <script type="module" src="/docs/assets/app.CaLG1pPt.js"></script>
12
+ <script type="module" src="/docs/assets/app.CRMxF0qX.js"></script>
13
13
  <link rel="preload" href="/docs/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
14
14
  <link rel="modulepreload" href="/docs/assets/chunks/framework.BNw1pucY.js">
15
- <link rel="modulepreload" href="/docs/assets/chunks/theme.DO1avLBn.js">
15
+ <link rel="modulepreload" href="/docs/assets/chunks/theme.m_Ethbkv.js">
16
16
  <link rel="modulepreload" href="/docs/assets/chunks/katex.DkKDou_j.js">
17
- <link rel="modulepreload" href="/docs/assets/chunks/dagre-KV5264BT.aSbEUwT7.js">
18
- <link rel="modulepreload" href="/docs/assets/chunks/cose-bilkent-S5V4N54A.tezXBs9b.js">
19
- <link rel="modulepreload" href="/docs/assets/chunks/c4Diagram-AHTNJAMY.w1d6QxV7.js">
20
- <link rel="modulepreload" href="/docs/assets/chunks/flowDiagram-DWJPFMVM.BFMtUSv-.js">
21
- <link rel="modulepreload" href="/docs/assets/chunks/erDiagram-SMLLAGMA.H40W4HWE.js">
22
- <link rel="modulepreload" href="/docs/assets/chunks/gitGraphDiagram-UUTBAWPF.Cyc5mzZD.js">
23
- <link rel="modulepreload" href="/docs/assets/chunks/ganttDiagram-T4ZO3ILL.CbYiu7Dt.js">
24
- <link rel="modulepreload" href="/docs/assets/chunks/infoDiagram-42DDH7IO.Bz6KCA3a.js">
25
- <link rel="modulepreload" href="/docs/assets/chunks/pieDiagram-DEJITSTG.BtpHnIB_.js">
26
- <link rel="modulepreload" href="/docs/assets/chunks/quadrantDiagram-34T5L4WZ.Cx4oCSRR.js">
27
- <link rel="modulepreload" href="/docs/assets/chunks/xychartDiagram-5P7HB3ND.b4pZF3D5.js">
28
- <link rel="modulepreload" href="/docs/assets/chunks/requirementDiagram-MS252O5E.BC0hXWlW.js">
29
- <link rel="modulepreload" href="/docs/assets/chunks/sequenceDiagram-FGHM5R23.CWSdHYAF.js">
30
- <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-6PBFFD2Q.Cmtm6WkN.js">
31
- <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-v2-HSJHXN6E.Cmtm6WkN.js">
32
- <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-FHFEXIEX.0MVPRI28.js">
33
- <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.N4Am6sXd.js">
34
- <link rel="modulepreload" href="/docs/assets/chunks/journeyDiagram-VCZTEJTY.D0t_ltlb.js">
35
- <link rel="modulepreload" href="/docs/assets/chunks/timeline-definition-GMOUNBTQ.BuRinAVi.js">
36
- <link rel="modulepreload" href="/docs/assets/chunks/mindmap-definition-QFDTVHPH.Bc72Utls.js">
37
- <link rel="modulepreload" href="/docs/assets/chunks/kanban-definition-6JOO6SKY.DyyNsMfi.js">
38
- <link rel="modulepreload" href="/docs/assets/chunks/sankeyDiagram-XADWPNL6.Dg8T1SEp.js">
39
- <link rel="modulepreload" href="/docs/assets/chunks/diagram-TYMM5635.BbAnLEBB.js">
40
- <link rel="modulepreload" href="/docs/assets/chunks/diagram-MMDJMWI5.CmdSUP6L.js">
41
- <link rel="modulepreload" href="/docs/assets/chunks/blockDiagram-DXYQGD6D.D51mJop2.js">
42
- <link rel="modulepreload" href="/docs/assets/chunks/diagram-5BDNPKRD.vnT6aJ57.js">
43
- <link rel="modulepreload" href="/docs/assets/chunks/architectureDiagram-Q4EWVU46.C5qkGp7y.js">
44
- <link rel="modulepreload" href="/docs/assets/chunks/ishikawaDiagram-UXIWVN3A.DDJ_7_Fq.js">
45
- <link rel="modulepreload" href="/docs/assets/chunks/vennDiagram-DHZGUBPP.DXf0PCoJ.js">
46
- <link rel="modulepreload" href="/docs/assets/chunks/diagram-G4DWMVQ6.hGYdrDa2.js">
47
- <link rel="modulepreload" href="/docs/assets/chunks/wardleyDiagram-NUSXRM2D.T4ThngYV.js">
17
+ <link rel="modulepreload" href="/docs/assets/chunks/dagre-KV5264BT.Bk_CcQPr.js">
18
+ <link rel="modulepreload" href="/docs/assets/chunks/cose-bilkent-S5V4N54A.4q0YNZN6.js">
19
+ <link rel="modulepreload" href="/docs/assets/chunks/c4Diagram-AHTNJAMY.D_Z3mqAl.js">
20
+ <link rel="modulepreload" href="/docs/assets/chunks/flowDiagram-DWJPFMVM.B61NGNYu.js">
21
+ <link rel="modulepreload" href="/docs/assets/chunks/erDiagram-SMLLAGMA.BN1YUmEV.js">
22
+ <link rel="modulepreload" href="/docs/assets/chunks/gitGraphDiagram-UUTBAWPF.CBPs2W_2.js">
23
+ <link rel="modulepreload" href="/docs/assets/chunks/ganttDiagram-T4ZO3ILL.DR-tto3M.js">
24
+ <link rel="modulepreload" href="/docs/assets/chunks/infoDiagram-42DDH7IO.obPv-fFg.js">
25
+ <link rel="modulepreload" href="/docs/assets/chunks/pieDiagram-DEJITSTG.BFp11AYt.js">
26
+ <link rel="modulepreload" href="/docs/assets/chunks/quadrantDiagram-34T5L4WZ.ChX7xo6B.js">
27
+ <link rel="modulepreload" href="/docs/assets/chunks/xychartDiagram-5P7HB3ND.DtXsNUaf.js">
28
+ <link rel="modulepreload" href="/docs/assets/chunks/requirementDiagram-MS252O5E.DbKtHG_Q.js">
29
+ <link rel="modulepreload" href="/docs/assets/chunks/sequenceDiagram-FGHM5R23.BYso9LlE.js">
30
+ <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-6PBFFD2Q.irslOV8B.js">
31
+ <link rel="modulepreload" href="/docs/assets/chunks/classDiagram-v2-HSJHXN6E.irslOV8B.js">
32
+ <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-FHFEXIEX.D8l54jqW.js">
33
+ <link rel="modulepreload" href="/docs/assets/chunks/stateDiagram-v2-QKLJ7IA2.CAYMmzGj.js">
34
+ <link rel="modulepreload" href="/docs/assets/chunks/journeyDiagram-VCZTEJTY.BoVHerYZ.js">
35
+ <link rel="modulepreload" href="/docs/assets/chunks/timeline-definition-GMOUNBTQ.BLdhhyy9.js">
36
+ <link rel="modulepreload" href="/docs/assets/chunks/mindmap-definition-QFDTVHPH.DLPMLJlv.js">
37
+ <link rel="modulepreload" href="/docs/assets/chunks/kanban-definition-6JOO6SKY.CfYmPHZg.js">
38
+ <link rel="modulepreload" href="/docs/assets/chunks/sankeyDiagram-XADWPNL6.Spw8tv-7.js">
39
+ <link rel="modulepreload" href="/docs/assets/chunks/diagram-TYMM5635.DSzlJp2D.js">
40
+ <link rel="modulepreload" href="/docs/assets/chunks/diagram-MMDJMWI5.BxtXxgIR.js">
41
+ <link rel="modulepreload" href="/docs/assets/chunks/blockDiagram-DXYQGD6D.sxrH_f0l.js">
42
+ <link rel="modulepreload" href="/docs/assets/chunks/diagram-5BDNPKRD.CgreoM_Z.js">
43
+ <link rel="modulepreload" href="/docs/assets/chunks/architectureDiagram-Q4EWVU46.CA-hBJCN.js">
44
+ <link rel="modulepreload" href="/docs/assets/chunks/ishikawaDiagram-UXIWVN3A.CXHTUcM3.js">
45
+ <link rel="modulepreload" href="/docs/assets/chunks/vennDiagram-DHZGUBPP.CyGT2F_P.js">
46
+ <link rel="modulepreload" href="/docs/assets/chunks/diagram-G4DWMVQ6.DlZGpm6W.js">
47
+ <link rel="modulepreload" href="/docs/assets/chunks/wardleyDiagram-NUSXRM2D.p_Sz9p1i.js">
48
48
  <link rel="modulepreload" href="/docs/assets/chunks/virtual_mermaid-config.DDnGl6nM.js">
49
- <link rel="modulepreload" href="/docs/assets/guides_webhooks.md.BBvAm_VF.lean.js">
49
+ <link rel="modulepreload" href="/docs/assets/guides_webhooks.md.Cpdc3BDX.lean.js">
50
50
  <script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
51
51
  <script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
52
52
  <link rel="alternate" type="text/plain" href="/docs/llms.txt">
53
53
  <link rel="alternate" type="text/markdown" href="/docs/guides/webhooks.md">
54
54
  </head>
55
55
  <body>
56
- <div id="app"><div class="Layout" data-v-5ebc75e4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-7de63af3></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-7de63af3>Skip to content</a><!--]--><!----><header class="VPNav" data-v-5ebc75e4 data-v-e8579816><div class="VPNavBar" data-v-e8579816 data-v-bbf4446f><div class="wrapper" data-v-bbf4446f><div class="container" data-v-bbf4446f><div class="title" data-v-bbf4446f><div class="VPNavBarTitle has-sidebar" data-v-bbf4446f data-v-ebd5f04e><a class="title" href="/docs/" data-v-ebd5f04e><!--[--><!--]--><!----><span data-v-ebd5f04e>Grok Bot Development Kit (BDK)</span><!--[--><!--[--><!--[--><!--[--><span class="bdk-version" title="BDK 0.2.13 (@cursor/bdk package)" data-v-d89e5038>0.2.13</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-bbf4446f><div class="content-body" data-v-bbf4446f><!--[--><!--]--><div class="VPNavBarSearch search" data-v-bbf4446f><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-bbf4446f data-v-7fa90d1c><span id="main-nav-aria-label" class="visually-hidden" data-v-7fa90d1c> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/mcp-oauth.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/github.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Integrations</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/templates/security-reviewer.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Templates</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-bbf4446f data-v-6a44a4fa><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6a44a4fa data-v-b541f24b data-v-a48af969><span class="check" data-v-a48af969><span class="icon" data-v-a48af969><!--[--><span class="vpi-sun sun" data-v-b541f24b></span><span class="vpi-moon moon" data-v-b541f24b></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-bbf4446f data-v-8d21ceac data-v-269c0ea1><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-269c0ea1><span class="vpi-more-horizontal icon" data-v-269c0ea1></span></button><div class="menu" data-v-269c0ea1><div class="VPMenu" data-v-269c0ea1 data-v-ab92b832><!----><!--[--><!--[--><!----><div class="group" data-v-8d21ceac><div class="item appearance" data-v-8d21ceac><p class="label" data-v-8d21ceac>Appearance</p><div class="appearance-action" data-v-8d21ceac><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-8d21ceac data-v-b541f24b data-v-a48af969><span class="check" data-v-a48af969><span class="icon" data-v-a48af969><!--[--><span class="vpi-sun sun" data-v-b541f24b></span><span class="vpi-moon moon" data-v-b541f24b></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-bbf4446f data-v-efff335d><span class="container" data-v-efff335d><span class="top" data-v-efff335d></span><span class="middle" data-v-efff335d></span><span class="bottom" data-v-efff335d></span></span></button></div></div></div></div><div class="divider" data-v-bbf4446f><div class="divider-line" data-v-bbf4446f></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-5ebc75e4 data-v-636a9279><div class="container" data-v-636a9279><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-636a9279><span class="vpi-align-left menu-icon" data-v-636a9279></span><span class="menu-text" data-v-636a9279>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-636a9279 data-v-ae38d8b4><button data-v-ae38d8b4>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-5ebc75e4 data-v-f102723c><div class="curtain" data-v-f102723c></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f102723c><span class="visually-hidden" id="sidebar-aria-label" data-v-f102723c> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Getting started</h2><!----></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Building your first agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible has-active" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Integrations</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Webhooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Cursor Automations</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>OpenTelemetry</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/gitlab.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>GitLab</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/bitbucket.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Bitbucket</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Extensions</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/extensions.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/cloud-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Cloud agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/grokbot-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Grok Bot agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/improve.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Self-improvement</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/jev.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Jev</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Guides</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>MCP</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/hooks.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Peer agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/deployment.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/migrate.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Early-alpha migration</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/evals.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Hillclimbing</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Build with a coding agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Troubleshooting</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Templates</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/grokbot-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Grok Bot agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/thermo-review.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Thermo review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/thermo-quality-review.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Thermo quality review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Agentic Approver</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/evals.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-5ebc75e4 data-v-4ab733be><div class="VPDoc has-sidebar has-aside" data-v-4ab733be data-v-4e7466dc><!--[--><!--]--><div class="container" data-v-4e7466dc><div class="aside" data-v-4e7466dc><div class="aside-curtain" data-v-4e7466dc></div><div class="aside-container" data-v-4e7466dc><div class="aside-content" data-v-4e7466dc><div class="VPDocAside" data-v-4e7466dc data-v-4f3f9a30><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-4f3f9a30 data-v-aacbb3fc><div class="content" data-v-aacbb3fc><div class="outline-marker" data-v-aacbb3fc></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-aacbb3fc>On this page</div><ul class="VPDocOutlineItem root" data-v-aacbb3fc data-v-0ffefe2a><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-4f3f9a30></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-4e7466dc><div class="content-container" data-v-4e7466dc><!--[--><!--]--><main class="main" data-v-4e7466dc><div style="position:relative;" class="vp-doc _docs_guides_webhooks" data-v-4e7466dc><div><h1 id="webhook-agents" tabindex="-1">Webhook agents <a class="header-anchor" href="#webhook-agents" aria-label="Permalink to &quot;Webhook agents&quot;">​</a></h1><p>A custom channel turns an event from another system into an agent conversation, then sends the result back to the system that started it. Use one when the built-in <a href="./../reference/http-api.html">HTTP API</a> does not match the provider&#39;s payload, conversation key, or reply path.</p><p>Author <code>bot/channels/&lt;id&gt;.ts</code>. Its routes mount under <code>/&lt;slug&gt;/v1/channels/&lt;id&gt;</code>.</p><h2 id="receive-a-webhook-and-send-the-answer-back" tabindex="-1">Receive a webhook and send the answer back <a class="header-anchor" href="#receive-a-webhook-and-send-the-answer-back" aria-label="Permalink to &quot;Receive a webhook and send the answer back&quot;">​</a></h2><p>When a ticket system sends a new message, this endpoint responds with <code>202 Accepted</code> right away. The agent keeps working after the HTTP request ends, and its completed answer appears as a comment on the ticket.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/channels/tickets.ts</span></span>
56
+ <div id="app"><div class="Layout" data-v-5ebc75e4><!--[--><!--]--><!--[--><span tabindex="-1" data-v-7de63af3></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-7de63af3>Skip to content</a><!--]--><!----><header class="VPNav" data-v-5ebc75e4 data-v-e8579816><div class="VPNavBar" data-v-e8579816 data-v-bbf4446f><div class="wrapper" data-v-bbf4446f><div class="container" data-v-bbf4446f><div class="title" data-v-bbf4446f><div class="VPNavBarTitle has-sidebar" data-v-bbf4446f data-v-ebd5f04e><a class="title" href="/docs/" data-v-ebd5f04e><!--[--><!--]--><!----><span data-v-ebd5f04e>Grok Bot Development Kit (BDK)</span><!--[--><!--[--><!--[--><!--[--><span class="bdk-version" title="BDK 0.2.15 (@cursor/bdk package)" data-v-d89e5038>0.2.15</span><!--]--><!--]--><!--]--><!--]--></a></div></div><div class="content" data-v-bbf4446f><div class="content-body" data-v-bbf4446f><!--[--><!--]--><div class="VPNavBarSearch search" data-v-bbf4446f><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-bbf4446f data-v-7fa90d1c><span id="main-nav-aria-label" class="visually-hidden" data-v-7fa90d1c> Main Navigation </span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/quickstart.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Quickstart</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/mcp-oauth.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Guides</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/guides/github.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Integrations</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/templates/security-reviewer.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Templates</span><!--]--></a><!--]--><!--[--><a class="VPLink link VPNavBarMenuLink" href="/docs/reference/project-layout.html" tabindex="0" data-v-7fa90d1c data-v-8d7ed182><!--[--><span data-v-8d7ed182>Reference</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-bbf4446f data-v-6a44a4fa><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-6a44a4fa data-v-b541f24b data-v-a48af969><span class="check" data-v-a48af969><span class="icon" data-v-a48af969><!--[--><span class="vpi-sun sun" data-v-b541f24b></span><span class="vpi-moon moon" data-v-b541f24b></span><!--]--></span></span></button></div><!----><div class="VPFlyout VPNavBarExtra extra" data-v-bbf4446f data-v-8d21ceac data-v-269c0ea1><button type="button" class="button" aria-haspopup="true" aria-expanded="false" aria-label="extra navigation" data-v-269c0ea1><span class="vpi-more-horizontal icon" data-v-269c0ea1></span></button><div class="menu" data-v-269c0ea1><div class="VPMenu" data-v-269c0ea1 data-v-ab92b832><!----><!--[--><!--[--><!----><div class="group" data-v-8d21ceac><div class="item appearance" data-v-8d21ceac><p class="label" data-v-8d21ceac>Appearance</p><div class="appearance-action" data-v-8d21ceac><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title aria-checked="false" data-v-8d21ceac data-v-b541f24b data-v-a48af969><span class="check" data-v-a48af969><span class="icon" data-v-a48af969><!--[--><span class="vpi-sun sun" data-v-b541f24b></span><span class="vpi-moon moon" data-v-b541f24b></span><!--]--></span></span></button></div></div></div><!----><!--]--><!--]--></div></div></div><!--[--><!--]--><button type="button" class="VPNavBarHamburger hamburger" aria-label="mobile navigation" aria-expanded="false" aria-controls="VPNavScreen" data-v-bbf4446f data-v-efff335d><span class="container" data-v-efff335d><span class="top" data-v-efff335d></span><span class="middle" data-v-efff335d></span><span class="bottom" data-v-efff335d></span></span></button></div></div></div></div><div class="divider" data-v-bbf4446f><div class="divider-line" data-v-bbf4446f></div></div></div><!----></header><div class="VPLocalNav has-sidebar empty" data-v-5ebc75e4 data-v-636a9279><div class="container" data-v-636a9279><button class="menu" aria-expanded="false" aria-controls="VPSidebarNav" data-v-636a9279><span class="vpi-align-left menu-icon" data-v-636a9279></span><span class="menu-text" data-v-636a9279>Menu</span></button><div class="VPLocalNavOutlineDropdown" style="--vp-vh:0px;" data-v-636a9279 data-v-ae38d8b4><button data-v-ae38d8b4>Return to top</button><!----></div></div></div><aside class="VPSidebar" data-v-5ebc75e4 data-v-f102723c><div class="curtain" data-v-f102723c></div><nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1" data-v-f102723c><span class="visually-hidden" id="sidebar-aria-label" data-v-f102723c> Sidebar Navigation </span><!--[--><!--]--><!--[--><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Getting started</h2><!----></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/quickstart.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Building your first agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible has-active" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Integrations</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/github.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>GitHub</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/slack.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Slack</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/webhooks.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Webhooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/convert-automation.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Cursor Automations</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/opentelemetry.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>OpenTelemetry</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/gitlab.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>GitLab</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/bitbucket.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Bitbucket</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Extensions</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/extensions.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Overview</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/cloud-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Cloud agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/grokbot-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Grok Bot agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/improve.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Self-improvement</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/jev.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Jev</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Guides</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/mcp-oauth.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>MCP</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/hooks.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/agent-to-agent.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Peer agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/deployment.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Deployment</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/guides/migrate.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Early-alpha migration</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/evals.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/hillclimbing.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Hillclimbing</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/building-with-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Build with a coding agent</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/troubleshooting.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Troubleshooting</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Templates</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/grokbot-agents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Grok Bot agents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/security-reviewer.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Security reviewer</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/thermo-review.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Thermo review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/thermo-quality-review.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Thermo quality review</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/agentic-owners.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Agentic Approver</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/templates/triage.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Triage agent</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><div class="no-transition group" data-v-9c447dd5><section class="VPSidebarItem level-0 collapsible" data-v-9c447dd5 data-v-8ccd545c><div class="item" role="button" tabindex="0" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><h2 class="text" data-v-8ccd545c>Reference</h2><div class="caret" role="button" aria-label="toggle section" tabindex="0" data-v-8ccd545c><span class="vpi-chevron-right caret-icon" data-v-8ccd545c></span></div></div><div class="items" data-v-8ccd545c><!--[--><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/project-layout.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Project layout</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/agent-config.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Agent config</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/instructions.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Instructions</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/tools.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Tools</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/prompt.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>prompt</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/skills.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Skills</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/connections.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>MCP Connections</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/subagents.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Subagents</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/channels.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Channels</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/schedules.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Schedules & reminders</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/hooks.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Hooks</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/evals.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Evals</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/artifacts.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Artifacts</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/sessions.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Sessions & streaming</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/playground.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>Playground</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/cli.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>CLI</p><!--]--></a><!----></div><!----></div><div class="VPSidebarItem level-1 is-link" data-v-8ccd545c><div class="item" data-v-8ccd545c><div class="indicator" data-v-8ccd545c></div><a class="VPLink link link" href="/docs/reference/http-api.html" data-v-8ccd545c><!--[--><p class="text" data-v-8ccd545c>HTTP API</p><!--]--></a><!----></div><!----></div><!--]--></div></section></div><!--]--><!--[--><!--]--></nav></aside><div class="VPContent has-sidebar" id="VPContent" data-v-5ebc75e4 data-v-4ab733be><div class="VPDoc has-sidebar has-aside" data-v-4ab733be data-v-4e7466dc><!--[--><!--]--><div class="container" data-v-4e7466dc><div class="aside" data-v-4e7466dc><div class="aside-curtain" data-v-4e7466dc></div><div class="aside-container" data-v-4e7466dc><div class="aside-content" data-v-4e7466dc><div class="VPDocAside" data-v-4e7466dc data-v-4f3f9a30><!--[--><!--]--><!--[--><!--]--><nav aria-labelledby="doc-outline-aria-label" class="VPDocAsideOutline" data-v-4f3f9a30 data-v-aacbb3fc><div class="content" data-v-aacbb3fc><div class="outline-marker" data-v-aacbb3fc></div><div aria-level="2" class="outline-title" id="doc-outline-aria-label" role="heading" data-v-aacbb3fc>On this page</div><ul class="VPDocOutlineItem root" data-v-aacbb3fc data-v-0ffefe2a><!--[--><!--]--></ul></div></nav><!--[--><!--]--><div class="spacer" data-v-4f3f9a30></div><!--[--><!--]--><!----><!--[--><!--]--><!--[--><!--]--></div></div></div></div><div class="content" data-v-4e7466dc><div class="content-container" data-v-4e7466dc><!--[--><!--]--><main class="main" data-v-4e7466dc><div style="position:relative;" class="vp-doc _docs_guides_webhooks" data-v-4e7466dc><div><h1 id="webhook-agents" tabindex="-1">Webhook agents <a class="header-anchor" href="#webhook-agents" aria-label="Permalink to &quot;Webhook agents&quot;">​</a></h1><p>A custom channel turns an event from another system into an agent conversation, then sends the result back to the system that started it. Use one when the built-in <a href="./../reference/http-api.html">HTTP API</a> does not match the provider&#39;s payload, conversation key, or reply path.</p><p>Author <code>bot/channels/&lt;id&gt;.ts</code>. Its routes mount under <code>/&lt;slug&gt;/v1/channels/&lt;id&gt;</code>.</p><h2 id="receive-a-webhook-and-send-the-answer-back" tabindex="-1">Receive a webhook and send the answer back <a class="header-anchor" href="#receive-a-webhook-and-send-the-answer-back" aria-label="Permalink to &quot;Receive a webhook and send the answer back&quot;">​</a></h2><p>When a ticket system sends a new message, this endpoint responds with <code>202 Accepted</code> and an empty body right away. The agent keeps working after the HTTP request ends, and its completed answer appears as a comment on the ticket.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// bot/channels/tickets.ts</span></span>
57
57
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineChannel, POST } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
58
58
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
59
59
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { postTicketComment } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../lib/tickets.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
@@ -78,7 +78,7 @@
78
78
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> title: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`Ticket ${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ticketId</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
79
79
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
80
80
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> );</span></span>
81
- <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ accepted: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">202</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
81
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Response</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">202</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
82
82
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
83
83
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }),</span></span>
84
84
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
@@ -90,7 +90,7 @@
90
90
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> postTicketComment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(channel.state.ticketId, event.data.text);</span></span>
91
91
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
92
92
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
93
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>postTicketComment</code> is a small wrapper around the ticket provider&#39;s SDK. Keeping that write in the event handler means the webhook request does not stay open while the model works.</p><h2 id="keep-one-conversation-per-ticket" tabindex="-1">Keep one conversation per ticket <a class="header-anchor" href="#keep-one-conversation-per-ticket" aria-label="Permalink to &quot;Keep one conversation per ticket&quot;">​</a></h2><p>Without a conversation key, every delivery creates a new session. Add the ticket ID as the <code>continuationToken</code> so the opening message and all later comments resume the same conversation, while a different ticket starts its own.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
93
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>postTicketComment</code> is a small wrapper around the ticket provider&#39;s SDK. Keeping that write in the event handler means the webhook request does not stay open while the model works.</p><p>The caller only ever receives that empty <code>202</code>. On Cursor-managed hosting, the deployment sends it before your handler runs and discards whatever the handler returns, so deliver every result, including failures, back through the provider&#39;s API. See <a href="./../reference/channels.html#route-responses">Route responses</a>.</p><h2 id="keep-one-conversation-per-ticket" tabindex="-1">Keep one conversation per ticket <a class="header-anchor" href="#keep-one-conversation-per-ticket" aria-label="Permalink to &quot;Keep one conversation per ticket&quot;">​</a></h2><p>Without a conversation key, every delivery creates a new session. Add the ticket ID as the <code>continuationToken</code> so the opening message and all later comments resume the same conversation, while a different ticket starts its own.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
94
94
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> send</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(body.message, {</span></span>
95
95
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> continuationToken: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">`ticket:${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">body</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ticketId</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}`</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
96
96
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> state: { ticketId: body.ticketId },</span></span>
@@ -101,10 +101,11 @@
101
101
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ticketId: body.ticketId,</span></span>
102
102
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
103
103
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (prepared.isError) {</span></span>
104
- <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
105
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { error: prepared.errorMessage </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">??</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;Could not prepare ticket&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
106
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">502</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
104
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> postTicketComment</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
105
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> body.ticketId,</span></span>
106
+ <span class="line"><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;I couldn&#39;t load this ticket, so I didn&#39;t draft a reply.&quot;</span></span>
107
107
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> );</span></span>
108
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Response</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">202</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
108
109
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
109
110
  <span class="line"></span>
110
111
  <span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> waitUntil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span></span>
@@ -116,8 +117,8 @@
116
117
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
117
118
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> })</span></span>
118
119
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> );</span></span>
119
- <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ accepted: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">202</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
120
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>The same <code>message.completed</code> handler from the first example delivers the answer back to the ticket.</p><h2 id="routes-receive-events-deliver" tabindex="-1">Routes receive, events deliver <a class="header-anchor" href="#routes-receive-events-deliver" aria-label="Permalink to &quot;Routes receive, events deliver&quot;">​</a></h2><p>Routes own inbound HTTP. A route validates the request, decides whether to start or resume a turn, and responds to the caller. The channel&#39;s <code>events</code> handlers receive session events later, which is where you deliver the model&#39;s answer or report a failure to the originating system.</p><h2 id="validate-payloads-with-zod" tabindex="-1">Validate payloads with Zod <a class="header-anchor" href="#validate-payloads-with-zod" aria-label="Permalink to &quot;Validate payloads with Zod&quot;">​</a></h2><p><code>POST</code>, <code>PUT</code>, and <code>PATCH</code> routes require a Zod <code>bodySchema</code>; <code>GET</code> requires a <code>querySchema</code>. Validation runs before the handler, and the parsed value arrives as typed <code>body</code> or <code>query</code>. Use <code>z.unknown()</code> when the provider controls a variable payload and your own parser will narrow it.</p><p>The route description and schema also appear in <code>GET /v1/info</code>. The playground uses them to add a <strong>Try</strong> action and a matching slash command, so you can exercise the same handler without building a separate test UI.</p><h2 id="use-handler-context" tabindex="-1">Use handler context <a class="header-anchor" href="#use-handler-context" aria-label="Permalink to &quot;Use handler context&quot;">​</a></h2><p>The handler context keeps deterministic setup and model work in one route:</p><ul><li><p><code>send</code> starts or resumes the agent conversation.</p></li><li><p><code>callTool</code> runs an authored server tool without starting a model turn.</p></li><li><p><code>waitUntil</code> keeps background work alive after the HTTP response. Await <code>send</code> when the caller needs the session handle, then call <code>session.waitForCompletion()</code> if it also needs the turn outcome.</p></li><li><p><code>host</code> provides authenticated services for API calls made by channel code.</p></li></ul><p>The full handler API lives in the <a href="./../reference/channels.html#handler-arguments">Channels reference</a>.</p><h2 id="protect-public-webhooks" tabindex="-1">Protect public webhooks <a class="header-anchor" href="#protect-public-webhooks" aria-label="Permalink to &quot;Protect public webhooks&quot;">​</a></h2><p>Custom routes accept direct loopback requests by default. They reject forwarded requests, so a tunnel or reverse proxy does not silently turn a local development endpoint into a public one.</p><p>Before accepting remote traffic, choose an explicit boundary. <code>bearerAuth()</code> works when the sender can attach an authorization header. On managed hosting, webhook providers often cannot attach the agent alias token, so <code>publicEndpoint()</code> lets that custom channel bypass it. That opens the route to every caller; verify the provider signature before starting a turn or calling a tool.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineChannel, POST, publicEndpoint } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
120
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Response</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">202</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
121
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">},</span></span></code></pre></div><p>The same <code>message.completed</code> handler from the first example delivers the answer back to the ticket. When preparation fails, the handler reports that on the ticket instead.</p><h2 id="routes-receive-events-deliver" tabindex="-1">Routes receive, events deliver <a class="header-anchor" href="#routes-receive-events-deliver" aria-label="Permalink to &quot;Routes receive, events deliver&quot;">​</a></h2><p>Routes own inbound HTTP. A route validates the request, decides whether to start or resume a turn, and acknowledges the caller with <code>202</code>. The channel&#39;s <code>events</code> handlers receive session events later, which is where you deliver the model&#39;s answer or report a failure to the originating system.</p><h2 id="validate-payloads-with-zod" tabindex="-1">Validate payloads with Zod <a class="header-anchor" href="#validate-payloads-with-zod" aria-label="Permalink to &quot;Validate payloads with Zod&quot;">​</a></h2><p><code>POST</code>, <code>PUT</code>, and <code>PATCH</code> routes require a Zod <code>bodySchema</code>; <code>GET</code> requires a <code>querySchema</code>. Validation runs before the handler, and the parsed value arrives as typed <code>body</code> or <code>query</code>. Use <code>z.unknown()</code> when the provider controls a variable payload and your own parser will narrow it.</p><p>The route description and schema also appear in <code>GET /v1/info</code>. The playground uses them to add a <strong>Try</strong> action and a matching slash command, so you can exercise the same handler without building a separate test UI.</p><h2 id="use-handler-context" tabindex="-1">Use handler context <a class="header-anchor" href="#use-handler-context" aria-label="Permalink to &quot;Use handler context&quot;">​</a></h2><p>The handler context keeps deterministic setup and model work in one route:</p><ul><li><p><code>send</code> starts or resumes the agent conversation.</p></li><li><p><code>callTool</code> runs an authored server tool without starting a model turn.</p></li><li><p><code>waitUntil</code> keeps background work alive after the handler returns. Await <code>send</code> when later handler code needs the session handle, such as calling <code>session.waitForCompletion()</code> before reporting the turn outcome to the provider.</p></li><li><p><code>host</code> provides authenticated services for API calls made by channel code.</p></li></ul><p>The full handler API lives in the <a href="./../reference/channels.html#handler-arguments">Channels reference</a>.</p><h2 id="protect-public-webhooks" tabindex="-1">Protect public webhooks <a class="header-anchor" href="#protect-public-webhooks" aria-label="Permalink to &quot;Protect public webhooks&quot;">​</a></h2><p>Custom routes accept direct loopback requests by default. They reject forwarded requests, so a tunnel or reverse proxy does not silently turn a local development endpoint into a public one.</p><p>Before accepting remote traffic, choose an explicit boundary. <code>bearerAuth()</code> works when the sender can attach an authorization header. On managed hosting, webhook providers often cannot attach the agent alias token, so <code>publicEndpoint()</code> lets that custom channel bypass it. That opens the route to every caller; verify the provider signature before starting a turn or calling a tool.</p><div class="language-ts vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">ts</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { defineChannel, POST, publicEndpoint } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;@cursor/bdk/channels&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
121
122
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { z } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;zod&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
122
123
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { verifyProviderSignature } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &quot;../lib/tickets.js&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
123
124
  <span class="line"></span>
@@ -131,21 +132,21 @@
131
132
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> rawBody</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> await</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> request.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">text</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">();</span></span>
132
133
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> signature</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> request.headers.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">get</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;x-provider-signature&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
133
134
  <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">!</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">verifyProviderSignature</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(rawBody, signature)) {</span></span>
134
- <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ ok: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">false</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">401</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
135
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Response</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">202</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
135
136
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }</span></span>
136
137
  <span class="line"></span>
137
138
  <span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> // Parse and dispatch only after the signature passes.</span></span>
138
- <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> Response.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">json</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">({ ok: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">true</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
139
+ <span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> return</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> new</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Response</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">null</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, { status: </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">202</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> });</span></span>
139
140
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> },</span></span>
140
141
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> }),</span></span>
141
142
  <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ],</span></span>
142
- <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p><code>publicEndpoint()</code> only opens this channel&#39;s routes. The built-in session and tool APIs stay private. See <a href="./../reference/channels.html#auth-policies">Auth policies</a> for bearer tokens and the complete policy reference.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to &quot;Test locally&quot;">​</a></h2><p>Run the agent in development mode, then replay the same payload the provider will send. The response should return immediately, and the resulting session should appear in the playground while the reply is delivered.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk serve --dir . --dev</span></span>
143
+ <span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><p>Because a hosted handler runs after the <code>202</code>, a delivery with a bad signature is dropped silently rather than rejected. When the provider sends a shared secret header or signs the raw body with HMAC-SHA256, use <code>sharedSecretAuth()</code> or <code>hmacSignatureAuth()</code> instead. Hosting checks those policies before the handler runs and answers a bad delivery with <code>401</code>.</p><p><code>publicEndpoint()</code> only opens this channel&#39;s routes. The built-in session and tool APIs stay private. See <a href="./../reference/channels.html#auth-policies">Auth policies</a> for bearer tokens and the complete policy reference.</p><h2 id="test-locally" tabindex="-1">Test locally <a class="header-anchor" href="#test-locally" aria-label="Permalink to &quot;Test locally&quot;">​</a></h2><p>Run the agent in development mode, then replay the same payload the provider will send. The route should answer <code>202</code> with an empty body right away, and the resulting session should appear in the playground while the reply is delivered.</p><div class="language-text vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">text</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>bdk serve --dir . --dev</span></span>
143
144
  <span class="line"><span></span></span>
144
145
  <span class="line"><span>curl -sS -X POST \</span></span>
145
146
  <span class="line"><span> http://127.0.0.1:3000/&lt;slug&gt;/v1/channels/tickets/ticket \</span></span>
146
147
  <span class="line"><span> -H &#39;content-type: application/json&#39; \</span></span>
147
148
  <span class="line"><span> -d &#39;{&quot;ticketId&quot;:&quot;ENG-142&quot;,&quot;message&quot;:&quot;CSV export returns 500&quot;}&#39;</span></span></code></pre></div><p>Keep representative payloads under <code>fixtures/</code> and pass them with <code>--data-binary @fixtures/&lt;event&gt;.json</code>. You can also open the route&#39;s <strong>Try</strong> action in the playground for manual probes.</p><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to &quot;Related&quot;">​</a></h2><ul><li><a href="./../reference/channels.html">Channels reference</a>: route methods, handler arguments, events, state, and auth policies</li><li><a href="./../templates/triage.html">Triage Linear or Jira issues</a>: a complete signed tracker webhook with reply delivery</li><li><a href="./../reference/http-api.html">HTTP API</a>: built-in session, follow-up, stream, and tool routes</li><li><a href="./../deployment.html#use-the-hosted-agent">Deployment</a>: stable hosted URLs and alias-token behavior</li><li><a href="./../evals.html">Evals</a>: turn saved payloads into regression fixtures</li></ul></div></div></main><footer class="VPDocFooter" data-v-4e7466dc data-v-5e6607d6><!--[--><!--]--><!----><nav class="prev-next" aria-labelledby="doc-footer-aria-label" data-v-5e6607d6><span class="visually-hidden" id="doc-footer-aria-label" data-v-5e6607d6>Pager</span><div class="pager" data-v-5e6607d6><a class="VPLink link pager-link prev" href="/docs/guides/slack.html" data-v-5e6607d6><!--[--><span class="desc" data-v-5e6607d6>Previous page</span><span class="title" data-v-5e6607d6>Slack</span><!--]--></a></div><div class="pager" data-v-5e6607d6><a class="VPLink link pager-link next" href="/docs/guides/convert-automation.html" data-v-5e6607d6><!--[--><span class="desc" data-v-5e6607d6>Next page</span><span class="title" data-v-5e6607d6>Cursor Automations</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
148
- <script>window.__VP_HASH_MAP__=JSON.parse("{\"building-with-agents.md\":\"Df87rAe1\",\"deployment.md\":\"BYuEcDBv\",\"evals.md\":\"C851kViu\",\"guides_agent-to-agent.md\":\"Cps5NiCV\",\"guides_bitbucket.md\":\"CKUayYtD\",\"guides_cloud-agents.md\":\"CWJjS9No\",\"guides_convert-automation.md\":\"DMEX9nF-\",\"guides_github.md\":\"TuNiZAOQ\",\"guides_gitlab.md\":\"CtNI4fSH\",\"guides_grokbot-agents.md\":\"tD1smFhU\",\"guides_hooks.md\":\"5Ce3NXxZ\",\"guides_improve.md\":\"CRrYq22s\",\"guides_jev.md\":\"D7XH4JH3\",\"guides_mcp-oauth.md\":\"DR3zhC9r\",\"guides_migrate.md\":\"sCAvvlC6\",\"guides_opentelemetry.md\":\"jcPNrQbH\",\"guides_slack.md\":\"Bn-WupSE\",\"guides_webhooks.md\":\"BBvAm_VF\",\"hillclimbing.md\":\"Dxvd-0gT\",\"index.md\":\"Dxxr7pFa\",\"quickstart.md\":\"BK5gjHM2\",\"reference_agent-config.md\":\"DrtLxWgR\",\"reference_artifacts.md\":\"DLV9MZES\",\"reference_channels.md\":\"LbNIJBwd\",\"reference_cli.md\":\"dYCAL2lB\",\"reference_connections.md\":\"DLrgAd5f\",\"reference_evals.md\":\"D5i8PuXJ\",\"reference_extensions.md\":\"OUacPetl\",\"reference_hooks.md\":\"B-eGa2km\",\"reference_http-api.md\":\"DbFNOubV\",\"reference_instructions.md\":\"DrcHZXig\",\"reference_playground.md\":\"1hx0gcIu\",\"reference_project-layout.md\":\"C2JMRh7p\",\"reference_prompt.md\":\"DqPh71XN\",\"reference_schedules.md\":\"BuJ8fgMa\",\"reference_sessions.md\":\"CyM7ARz1\",\"reference_skills.md\":\"C0guGcH0\",\"reference_subagents.md\":\"gmPt5J-M\",\"reference_tools.md\":\"DzIY9JzY\",\"templates_agentic-owners.md\":\"CvmABtia\",\"templates_grokbot-agents.md\":\"2sydjFiO\",\"templates_security-reviewer.md\":\"Gh6EF9Us\",\"templates_thermo-quality-review.md\":\"B77UyTrX\",\"templates_thermo-review.md\":\"DRJ7mC5U\",\"templates_triage.md\":\"CNN6b0JZ\",\"troubleshooting.md\":\"x-GBa7wN\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Grok Bot Development Kit (BDK)\",\"description\":\"Build and serve bots and agents from versioned Markdown and TypeScript.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.2.13\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Integrations\",\"link\":\"/guides/github\"},{\"text\":\"Templates\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Building your first agent\",\"link\":\"/quickstart\"}]},{\"text\":\"Integrations\",\"collapsed\":false,\"items\":[{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Webhooks\",\"link\":\"/guides/webhooks\"},{\"text\":\"Cursor Automations\",\"link\":\"/guides/convert-automation\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"},{\"text\":\"GitLab\",\"link\":\"/guides/gitlab\"},{\"text\":\"Bitbucket\",\"link\":\"/guides/bitbucket\"}]},{\"text\":\"Extensions\",\"collapsed\":false,\"items\":[{\"text\":\"Overview\",\"link\":\"/reference/extensions\"},{\"text\":\"Cloud agents\",\"link\":\"/guides/cloud-agents\"},{\"text\":\"Grok Bot agents\",\"link\":\"/guides/grokbot-agents\"},{\"text\":\"Self-improvement\",\"link\":\"/guides/improve\"},{\"text\":\"Jev\",\"link\":\"/guides/jev\"}]},{\"text\":\"Guides\",\"collapsed\":false,\"items\":[{\"text\":\"MCP\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Hooks\",\"link\":\"/guides/hooks\"},{\"text\":\"Peer agents\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Early-alpha migration\",\"link\":\"/guides/migrate\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"},{\"text\":\"Build with a coding agent\",\"link\":\"/building-with-agents\"},{\"text\":\"Troubleshooting\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Templates\",\"collapsed\":false,\"items\":[{\"text\":\"Grok Bot agents\",\"link\":\"/templates/grokbot-agents\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Thermo review\",\"link\":\"/templates/thermo-review\"},{\"text\":\"Thermo quality review\",\"link\":\"/templates/thermo-quality-review\"},{\"text\":\"Agentic Approver\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Evals\",\"link\":\"/reference/evals\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
149
+ <script>window.__VP_HASH_MAP__=JSON.parse("{\"building-with-agents.md\":\"Bi9CQ-bR\",\"deployment.md\":\"hKKN9I4c\",\"evals.md\":\"CHR34K1Y\",\"guides_agent-to-agent.md\":\"Cps5NiCV\",\"guides_bitbucket.md\":\"CKUayYtD\",\"guides_cloud-agents.md\":\"CBK7W0-O\",\"guides_convert-automation.md\":\"DMEX9nF-\",\"guides_github.md\":\"TuNiZAOQ\",\"guides_gitlab.md\":\"CtNI4fSH\",\"guides_grokbot-agents.md\":\"BwAykJ7U\",\"guides_hooks.md\":\"B_bKG1oA\",\"guides_improve.md\":\"CZKVt1cT\",\"guides_jev.md\":\"D7XH4JH3\",\"guides_mcp-oauth.md\":\"BM_eFC0L\",\"guides_migrate.md\":\"sCAvvlC6\",\"guides_opentelemetry.md\":\"jcPNrQbH\",\"guides_slack.md\":\"Bn-WupSE\",\"guides_webhooks.md\":\"Cpdc3BDX\",\"hillclimbing.md\":\"Dxvd-0gT\",\"index.md\":\"BIBHIQtU\",\"quickstart.md\":\"CduLGBAB\",\"reference_agent-config.md\":\"DrtLxWgR\",\"reference_artifacts.md\":\"DLV9MZES\",\"reference_channels.md\":\"DYg0CLud\",\"reference_cli.md\":\"BYNIHwbi\",\"reference_connections.md\":\"CxbLpaaP\",\"reference_evals.md\":\"if--BLd0\",\"reference_extensions.md\":\"OUacPetl\",\"reference_hooks.md\":\"DbJC8mcZ\",\"reference_http-api.md\":\"CrqhTv6S\",\"reference_instructions.md\":\"DrcHZXig\",\"reference_playground.md\":\"q4MI-0td\",\"reference_project-layout.md\":\"C2JMRh7p\",\"reference_prompt.md\":\"DqPh71XN\",\"reference_schedules.md\":\"03Ryy9ca\",\"reference_sessions.md\":\"C_uzIWuy\",\"reference_skills.md\":\"Ckddg6KX\",\"reference_subagents.md\":\"gmPt5J-M\",\"reference_tools.md\":\"08XR7lIl\",\"templates_agentic-owners.md\":\"CvmABtia\",\"templates_grokbot-agents.md\":\"DgpPEs7B\",\"templates_security-reviewer.md\":\"Gh6EF9Us\",\"templates_thermo-quality-review.md\":\"B77UyTrX\",\"templates_thermo-review.md\":\"DRJ7mC5U\",\"templates_triage.md\":\"CNN6b0JZ\",\"troubleshooting.md\":\"PCafNCb5\"}");window.__VP_SITE_DATA__=JSON.parse("{\"lang\":\"en-US\",\"dir\":\"ltr\",\"title\":\"Grok Bot Development Kit (BDK)\",\"description\":\"Build and serve bots and agents from versioned Markdown and TypeScript.\",\"base\":\"/docs/\",\"head\":[],\"router\":{\"prefetchLinks\":true},\"appearance\":true,\"themeConfig\":{\"sdkVersion\":\"0.2.15\",\"nav\":[{\"text\":\"Quickstart\",\"link\":\"/quickstart\"},{\"text\":\"Guides\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Integrations\",\"link\":\"/guides/github\"},{\"text\":\"Templates\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Reference\",\"link\":\"/reference/project-layout\"}],\"search\":{\"provider\":\"local\"},\"outline\":{\"level\":[2,3]},\"sidebar\":[{\"text\":\"Getting started\",\"items\":[{\"text\":\"Overview\",\"link\":\"/\"},{\"text\":\"Building your first agent\",\"link\":\"/quickstart\"}]},{\"text\":\"Integrations\",\"collapsed\":false,\"items\":[{\"text\":\"GitHub\",\"link\":\"/guides/github\"},{\"text\":\"Slack\",\"link\":\"/guides/slack\"},{\"text\":\"Webhooks\",\"link\":\"/guides/webhooks\"},{\"text\":\"Cursor Automations\",\"link\":\"/guides/convert-automation\"},{\"text\":\"OpenTelemetry\",\"link\":\"/guides/opentelemetry\"},{\"text\":\"GitLab\",\"link\":\"/guides/gitlab\"},{\"text\":\"Bitbucket\",\"link\":\"/guides/bitbucket\"}]},{\"text\":\"Extensions\",\"collapsed\":false,\"items\":[{\"text\":\"Overview\",\"link\":\"/reference/extensions\"},{\"text\":\"Cloud agents\",\"link\":\"/guides/cloud-agents\"},{\"text\":\"Grok Bot agents\",\"link\":\"/guides/grokbot-agents\"},{\"text\":\"Self-improvement\",\"link\":\"/guides/improve\"},{\"text\":\"Jev\",\"link\":\"/guides/jev\"}]},{\"text\":\"Guides\",\"collapsed\":false,\"items\":[{\"text\":\"MCP\",\"link\":\"/guides/mcp-oauth\"},{\"text\":\"Hooks\",\"link\":\"/guides/hooks\"},{\"text\":\"Peer agents\",\"link\":\"/guides/agent-to-agent\"},{\"text\":\"Deployment\",\"link\":\"/deployment\"},{\"text\":\"Early-alpha migration\",\"link\":\"/guides/migrate\"},{\"text\":\"Evals\",\"link\":\"/evals\"},{\"text\":\"Hillclimbing\",\"link\":\"/hillclimbing\"},{\"text\":\"Build with a coding agent\",\"link\":\"/building-with-agents\"},{\"text\":\"Troubleshooting\",\"link\":\"/troubleshooting\"}]},{\"text\":\"Templates\",\"collapsed\":false,\"items\":[{\"text\":\"Grok Bot agents\",\"link\":\"/templates/grokbot-agents\"},{\"text\":\"Security reviewer\",\"link\":\"/templates/security-reviewer\"},{\"text\":\"Thermo review\",\"link\":\"/templates/thermo-review\"},{\"text\":\"Thermo quality review\",\"link\":\"/templates/thermo-quality-review\"},{\"text\":\"Agentic Approver\",\"link\":\"/templates/agentic-owners\"},{\"text\":\"Triage agent\",\"link\":\"/templates/triage\"}]},{\"text\":\"Reference\",\"collapsed\":false,\"items\":[{\"text\":\"Project layout\",\"link\":\"/reference/project-layout\"},{\"text\":\"Agent config\",\"link\":\"/reference/agent-config\"},{\"text\":\"Instructions\",\"link\":\"/reference/instructions\"},{\"text\":\"Tools\",\"link\":\"/reference/tools\"},{\"text\":\"prompt\",\"link\":\"/reference/prompt\"},{\"text\":\"Skills\",\"link\":\"/reference/skills\"},{\"text\":\"MCP Connections\",\"link\":\"/reference/connections\"},{\"text\":\"Subagents\",\"link\":\"/reference/subagents\"},{\"text\":\"Channels\",\"link\":\"/reference/channels\"},{\"text\":\"Schedules & reminders\",\"link\":\"/reference/schedules\"},{\"text\":\"Hooks\",\"link\":\"/reference/hooks\"},{\"text\":\"Evals\",\"link\":\"/reference/evals\"},{\"text\":\"Artifacts\",\"link\":\"/reference/artifacts\"},{\"text\":\"Sessions & streaming\",\"link\":\"/reference/sessions\"},{\"text\":\"Playground\",\"link\":\"/reference/playground\"},{\"text\":\"CLI\",\"link\":\"/reference/cli\"},{\"text\":\"HTTP API\",\"link\":\"/reference/http-api\"}]}]},\"locales\":{},\"scrollOffset\":134,\"cleanUrls\":false}");</script>
149
150
 
150
151
  </body>
151
152
  </html>
package/dist/docs/guides/webhooks.md CHANGED
@@ -11,9 +11,9 @@ Author `bot/channels/<id>.ts`. Its routes mount under
11
11
  ## Receive a webhook and send the answer back
12
12
 
13
13
  When a ticket system sends a new message, this endpoint responds with
14
- `202 Accepted` right away. The agent keeps working after the HTTP
15
- request ends, and its completed answer appears as a comment on the
16
- ticket.
14
+ `202 Accepted` and an empty body right away. The agent keeps working
15
+ after the HTTP request ends, and its completed answer appears as a
16
+ comment on the ticket.
17
17
 
18
18
  ```ts
19
19
  // bot/channels/tickets.ts
@@ -41,7 +41,7 @@ export default defineChannel<TicketState>({
41
41
  title: `Ticket ${body.ticketId}`,
42
42
  })
43
43
  );
44
- return Response.json({ accepted: true }, { status: 202 });
44
+ return new Response(null, { status: 202 });
45
45
  },
46
46
  }),
47
47
  ],
@@ -60,6 +60,12 @@ export default defineChannel<TicketState>({
60
60
  SDK. Keeping that write in the event handler means the webhook request
61
61
  does not stay open while the model works.
62
62
 
63
+ The caller only ever receives that empty `202`. On Cursor-managed
64
+ hosting, the deployment sends it before your handler runs and discards
65
+ whatever the handler returns, so deliver every result, including
66
+ failures, back through the provider's API. See
67
+ [Route responses](/docs/reference/channels.md#route-responses).
68
+
63
69
  ## Keep one conversation per ticket
64
70
 
65
71
  Without a conversation key, every delivery creates a new session. Add
@@ -93,10 +99,11 @@ handler: async (_request, { callTool, send, waitUntil, body }) => {
93
99
  ticketId: body.ticketId,
94
100
  });
95
101
  if (prepared.isError) {
96
- return Response.json(
97
- { error: prepared.errorMessage ?? "Could not prepare ticket" },
98
- { status: 502 }
102
+ await postTicketComment(
103
+ body.ticketId,
104
+ "I couldn't load this ticket, so I didn't draft a reply."
99
105
  );
106
+ return new Response(null, { status: 202 });
100
107
  }
101
108
 
102
109
  waitUntil(
@@ -108,17 +115,19 @@ handler: async (_request, { callTool, send, waitUntil, body }) => {
108
115
  },
109
116
  })
110
117
  );
111
- return Response.json({ accepted: true }, { status: 202 });
118
+ return new Response(null, { status: 202 });
112
119
  },
113
120
  ```
114
121
 
115
122
  The same `message.completed` handler from the first example delivers
116
- the answer back to the ticket.
123
+ the answer back to the ticket. When preparation fails, the handler
124
+ reports that on the ticket instead.
117
125
 
118
126
  ## Routes receive, events deliver
119
127
 
120
128
  Routes own inbound HTTP. A route validates the request, decides whether
121
- to start or resume a turn, and responds to the caller. The channel's
129
+ to start or resume a turn, and acknowledges the caller with `202`. The
130
+ channel's
122
131
  `events` handlers receive session events later, which is where you
123
132
  deliver the model's answer or report a failure to the originating
124
133
  system.
@@ -146,9 +155,10 @@ route:
146
155
  - `callTool` runs an authored server tool without starting a model
147
156
  turn.
148
157
 
149
- - `waitUntil` keeps background work alive after the HTTP response. Await
150
- `send` when the caller needs the session handle, then call
151
- `session.waitForCompletion()` if it also needs the turn outcome.
158
+ - `waitUntil` keeps background work alive after the handler returns.
159
+ Await `send` when later handler code needs the session handle, such
160
+ as calling `session.waitForCompletion()` before reporting the turn
161
+ outcome to the provider.
152
162
 
153
163
  - `host` provides authenticated services for API calls made by channel
154
164
  code.
@@ -184,17 +194,24 @@ export default defineChannel({
184
194
  const rawBody = await request.text();
185
195
  const signature = request.headers.get("x-provider-signature");
186
196
  if (!verifyProviderSignature(rawBody, signature)) {
187
- return Response.json({ ok: false }, { status: 401 });
197
+ return new Response(null, { status: 202 });
188
198
  }
189
199
 
190
200
  // Parse and dispatch only after the signature passes.
191
- return Response.json({ ok: true });
201
+ return new Response(null, { status: 202 });
192
202
  },
193
203
  }),
194
204
  ],
195
205
  });
196
206
  ```
197
207
 
208
+ Because a hosted handler runs after the `202`, a delivery with a bad
209
+ signature is dropped silently rather than rejected. When the provider
210
+ sends a shared secret header or signs the raw body with HMAC-SHA256,
211
+ use `sharedSecretAuth()` or `hmacSignatureAuth()` instead. Hosting
212
+ checks those policies before the handler runs and answers a bad
213
+ delivery with `401`.
214
+
198
215
  `publicEndpoint()` only opens this channel's routes. The built-in
199
216
  session and tool APIs stay private. See
200
217
  [Auth policies](/docs/reference/channels.md#auth-policies) for bearer
@@ -203,9 +220,9 @@ tokens and the complete policy reference.
203
220
  ## Test locally
204
221
 
205
222
  Run the agent in development mode, then replay the same payload the
206
- provider will send. The response should return immediately, and the
207
- resulting session should appear in the playground while the reply is
208
- delivered.
223
+ provider will send. The route should answer `202` with an empty body
224
+ right away, and the resulting session should appear in the playground
225
+ while the reply is delivered.
209
226
 
210
227
  ```text
211
228
  bdk serve --dir . --dev