Webhook 投递链路
理解 EdgeCron 从触发到投递、重试和死信的核心概念。
EdgeCron 的核心不是“一个 cron 表达式”，而是一条可观察、可重试、可恢复的 Webhook 投递链路。
回调端点
01
触发来源
02
执行任务
03
投递尝试
04
重试任务
05
死信
06
核心对象
Endpoint / 回调端点
投递到哪里
目标 Webhook 地址。它包含回调 URL、方法、请求头、超时、可选签名密钥、重试策略绑定和事件订阅。
Schedule Trigger / 调度触发
什么时候投递
cron 或一次性时间规则。它到点后创建 Task Run；它本身不会直接发起 HTTP 请求。
Event Trigger / 事件触发
为什么投递
命名业务事件，例如 invoice.paid。Endpoint 过滤规则决定哪些目标接收事件，然后 fan-out 创建 Task Run。
Task Run / 执行任务
一次执行实例
由调度、事件 fan-out 或直接 API 调用创建的运行时工作。用于跟踪状态或取消待执行任务。
Delivery Attempt / 投递尝试
一次 HTTP 调用
对 Endpoint 的一次出站请求。它记录状态码、耗时、响应摘要、错误信息、尝试次数和 trace 信息。
Retry Job / 重试任务
一次恢复任务
由可重试的失败投递创建的队列任务。重试策略控制最大尝试次数和退避方式。
一次请求如何流动
回调端点
配置 EdgeCron 要调用哪里：URL、方法、请求头、超时、签名密钥、重试策略和事件过滤。
触发来源
调度触发、事件发布或直接 API 调用决定为什么以及什么时候开始执行。
执行任务
EdgeCron 创建一个绑定 Endpoint 和 payload 的具体运行实例。
投递尝试
Worker 发起 HTTP 调用，并记录状态、耗时、响应内容和 request_id。
重试任务
可重试失败会根据策略进入固定、线性或指数退避队列。
死信
超过最大尝试次数的失败会保留为死信，等待人工检查、重放或补偿。
两种最常见触发
调度触发
你创建 Schedule，设置 cron 或一次性时间。到点后调度器创建 Task Run，Worker 再对 Endpoint 发起 Delivery Attempt。
事件触发
你的系统发布 Event，例如 invoice.paid。EdgeCron 根据 Endpoint 的事件过滤规则做 fan-out，并为每个匹配端点创建 Task Run。
直接任务
你也可以直接创建 Task Run，用于立即投递、延迟一次性投递或补偿业务流程。
出站 fan-out
Event fan-out 指的是出站投递 fan-out。你发布 Event 后，EdgeCron 会检查当前 App 下每个 active Endpoint，并应用该 Endpoint 的 filter_events 规则。每个匹配的 Endpoint 都会得到独立的 Task Run 和 Delivery Attempt 历史。
因此，一个 Event 可以创建多个 Task Run，但计费仍然按触发口径处理：这次 Event 发布只算一个 billable trigger，fan-out 产生的 Delivery Attempt 包含在内。
这和 Hookdeck 风格的入站网关不同。EdgeCron 目前还不是通过托管 Source URL 接收第三方 Webhook，再按 Source -> Connection -> Destination 规则路由的 inbound gateway。
Schedule endpoint binding
Schedule 可以指定 endpoint_ids。当 Schedule 有显式 endpoint 绑定时，它只会为这些 Endpoint 创建 Task Run。当绑定列表为空时，EdgeCron 保持向后兼容行为，把这次 Schedule 触发发送给当前 App 下所有 active Endpoint。
如果一个 Schedule 只应该驱动特定流程，例如 daily-report -> reporting-api，请使用显式绑定，而不是广播到所有 Endpoint。
重试判定
Worker 会先判定投递结果，再决定是否创建 Retry Job：
2xx响应视为成功。5xx、网络错误和超时可重试。4xx默认视为终态失败。429只有在响应包含合法Retry-After头时才会重试。EdgeCron 支持秒数和 HTTP-date 两种格式，并会把延迟限制在 Retry Policy 的max_delay_sec内。
运行状态怎么理解
pending / running
Task Run 等待执行或正在执行。此时还不代表目标 Endpoint 已经成功收到请求。
success
目标 Endpoint 返回 2xx，Delivery Attempt 被视为成功，Task Run 可以结束。
failed / retry_scheduled
请求超时、网络错误或可重试状态会进入失败记录，并根据 Retry Policy 安排后续 Retry Job。
dead_letter
重试次数耗尽后进入死信，用于人工排障、手动重放或业务补偿。
不要混淆
- Endpoint 不是 Event：Endpoint 是投递目标，Event 是触发输入。
- Schedule 不直接发 HTTP：Schedule 到点后创建 Task Run，Worker 执行投递。
- Task Run 不是模板：它是一次运行实例，不是可复用任务定义。
- Delivery Attempt 不是 Task Run：一个 Task Run 可以产生多次投递尝试。