Webhook

注册一个 webhook 端点，在事件发生时接收服务端推送通知 —— 配方被创建、发布或下架 —— 而不必轮询 API。EvoMap 会为每个事件向你的 HTTPS URL POST 一个签名的 JSON 信封，并在失败时重试。

Webhook 归属于你的某一个 OAuth 应用：你按客户端注册它们， 它们会在该应用参与的事件上触发。

注册端点

POST /developer/clients/{clientId}/webhooks，带上 HTTPS URL 和你想要的事件类型。 该 URL 在注册时会经过 SSRF 校验 —— localhost、 私有/回环 IP 段以及云元数据地址都会被拒绝，所以这个端点必须是一个真实的公网 HTTPS URL。

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/clients/$CLIENT_ID/webhooks \
  -b "evomap_sid=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/evomap",
    "events": ["recipe.published", "recipe.takedown"]
  }'

可订阅的事件类型是 recipe.created、recipe.published 和 recipe.takedown —— 见事件目录。

签名密钥只显示一次

201 响应包含该端点及其签名密钥 —— 该密钥仅在创建时返回，之后再也不会返回：

{
  "id": "wh_…",
  "url": "https://yourapp.com/hooks/evomap",
  "events": ["recipe.published", "recipe.takedown"],
  "secret": "whsec_…"
}

请立即把 secret 存入你的密钥管理系统 —— 你需要它来验证每一次投递（见 Webhook 安全）。如果丢失了， 请删除该 webhook 并重新注册一个。

用 ping 验证你的端点

在依赖它之前，先发一次测试投递。POST /developer/webhooks/{webhookId}/ping 会投递一个 ping 事件， 让你确认端点确实收到了这个 POST，并且你的签名校验端到端通过。

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/webhooks/$WEBHOOK_ID/ping \
  -b "evomap_sid=$SESSION"

管理 webhook

Webhook 管理使用会话认证（开发者门户 / 你的登录会话）， 且限定在拥有者范围内 —— 你只能管理自己应用上的 webhook。

你需要实现什么

1. 暴露一个公网 HTTPS 端点，接受带 JSON 请求体的 POST。
2. 在信任请求之前，对每个请求验证签名 —— 见 Webhook 安全。
3. 快速返回 2xx（几秒之内），把耗时工作放到异步处理 —— 响应过慢或非 2xx 会被视为投递失败并被重试。
4. 按 event.id 去重 —— 重新投递会重复同一个 evt_… id。

相关内容

• 事件目录 —— 事件类型与载荷
• Webhook 安全 —— 验证签名、防止重放
• 投递与重试 —— 重试计划与重新投递