Custom API 渠道和事件推送用于把自有系统与 YundaDesk 连接起来。当前可用能力以产品中的套餐页为准。

套餐变化时会发生什么#

如果工作区切换到不再包含某项开发者集成能力的套餐：

• 已有配置、签名密钥和历史投递记录不会被删除。
• 对应的 Custom API 渠道或事件推送会被停用，不再发送新请求。
• 你仍可以查看、禁用或删除已有配置，但不能创建、启用、测试、重放或轮换密钥。
• 再次获得权益后不会自动恢复，请检查配置后手动启用。

配置回调地址#

回调地址或事件推送地址必须满足：

• 使用公网 https:// 地址，端口为 443。
• 地址中不能包含用户名、密码或 # 片段。
• 域名必须与保存的允许域名一致；如需允许多个子域，请显式配置受控的通配子域。
• 目标服务器需要能够从 YundaDesk 公布的固定出口 IP 接收请求。

保存后使用页面上的“测试”操作验证连接。测试成功只代表当前请求可达；正式使用前还应在目标系统核对签名、事件内容和来源 IP。

固定出口 IP#

YundaDesk 通过固定出口 IP 发送 Custom API callback 和事件 Webhook。页面默认不直接展开出口 IP；需要配置接收端时，点击蓝色的“查看白名单 IP”，再将显示的地址加入目标服务器白名单。

如果页面显示尚未公布出口 IP，请联系 YundaDesk 支持，不要自行放开所有来源。页面可能同时显示多个 IP，应全部加入白名单。

验证请求#

请在目标系统验证 YundaDesk 提供的签名和时间戳，并使用事件 ID 或投递 ID 做幂等处理。不要仅依赖来源 IP 作为身份验证。

Custom API 的公网入站地址以产品页面显示为准。重复提交同一条已签名的回执不会重复更新投递状态。

排查投递失败#

先在对应的 Custom API 或事件推送页面查看投递状态和错误类型：

• 套餐或额度限制：检查当前套餐和用量。
• 地址或域名被拒绝：检查 HTTPS、端口、域名和 URL 内容。
• 连接超时或目标不可用：确认目标服务在线，并允许所有已公布出口 IP。
• 签名失败：重新核对当前密钥；轮换后确保目标系统已使用新密钥。

临时网络或 DNS 故障会进入自动重试。达到最大重试次数后，再按页面提供的重放操作处理。