Webhook の追加 - Waffo Pancake

ストアに Webhook エンドポイントを追加します。各ストアでは、すべてのチャネルにわたって最大 20 個の Webhook を持つことができます。

POST /v1/actions/store/add-webhook

認証： API Key（owner または admin ロールが必要）

リクエストボディ

フィールド	型	必須	説明
`storeId`	string	Yes	Store ID（Short ID フォーマット `STO_xxx`）
`channel`	string	Yes	`http`、`feishu`、`discord`、`telegram`、`slack` のいずれか
`url`	string	Yes	Webhook 送信先 URL（HTTPS。マーチャントは URL が選択したチャネルと一致することを保証）
`events`	string[]	Yes	購読するイベントタイプ — 例：`["order.completed", "refund.succeeded"]`。空配列の場合、この Webhook にはイベントが配信されません。
`testMode`	boolean	Yes	`true` = テストトランザクションで発火、`false` = 本番で発火
`secret`	string \| null	No	チャネル固有の認証情報（例：Telegram の `chat_id`）。不透明なテキストとして保存されます。

リクエスト例

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

// Standard HTTPS webhook (RSA-signed envelope)
const { webhook } = await client.webhooks.add({
  storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  channel: "http",
  url: "https://example.com/webhooks/pancake",
  events: ["order.completed", "refund.succeeded"],
  testMode: false,
});

// Discord webhook — uses Discord's native embed format
await client.webhooks.add({
  storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  channel: "discord",
  url: "https://discord.com/api/webhooks/123456789/abc-def-ghi",
  events: ["order.completed"],
  testMode: false,
});

// Telegram bot — chat_id goes in secret
await client.webhooks.add({
  storeId: "STO_2aUyqjCzEIiEcYMKj7TZtw",
  channel: "telegram",
  url: "https://api.telegram.org/bot123456:ABC-DEF/sendMessage",
  events: ["order.completed", "refund.failed"],
  testMode: false,
  secret: "8737101383",
});

curl -X POST https://api.waffo.com/v1/actions/store/add-webhook \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $WAFFO_MERCHANT_ID" \
  -H "X-Signature: ..." \
  -d '{
    "storeId": "STO_2aUyqjCzEIiEcYMKj7TZtw",
    "channel": "http",
    "url": "https://example.com/webhooks/pancake",
    "events": ["order.completed"],
    "testMode": false
  }'

成功レスポンス (200)

{
  "data": {
    "webhook": {
      "id": "11111111-2222-3333-4444-555555555555",
      "storeId": "uuid-of-store",
      "channel": "http",
      "url": "https://example.com/webhooks/pancake",
      "events": ["order.completed", "refund.succeeded"],
      "testMode": false,
      "secret": null,
      "createdAt": "2026-05-07T00:00:00.000Z",
      "updatedAt": "2026-05-07T00:00:00.000Z"
    }
  }
}

返される webhook.id は UUID であり、Short ID ではありません — Webhook ID は IdPrefix のスコープに含まれません。update-webhook および remove-webhook にはそのまま渡してください。

レスポンスフィールド

フィールド	型	説明
`id`	string	Webhook UUID
`storeId`	string	所属ストアの UUID
`channel`	string	Webhook チャネル（`http`、`feishu`、`discord`、`telegram`、または `slack`）
`url`	string	送信先 Webhook URL
`events`	string[]	購読するイベントタイプ
`testMode`	boolean	`true` はテストトランザクションで発火、`false` は本番で発火
`secret`	string \| null	チャネル固有の認証情報（不透明テキスト）、未設定の場合は `null`
`createdAt`	string	作成タイムスタンプ（ISO 8601）
`updatedAt`	string	最終更新タイムスタンプ（ISO 8601）

エラー

リトライポリシー：4xx は一切リトライしない — リクエストを修正してから再送信。5xx は指数バックオフでリトライ（5s 開始、最大 3 回）。

ステータス	`errors[0].message`	意味	推奨処理
400	`Missing required field: storeId`	`storeId` が指定されていない	リクエストボディを修正して再送信
400	`Expected format: STO_xxx, got "..."`	`storeId` Short ID のデコード失敗	`storeId` のフォーマットを修正して再送信
400	`testMode must be a boolean`	`testMode` が boolean ではない	boolean 値を渡して再送信
400	`Invalid channel: must be one of http, feishu, discord, telegram, slack`	`channel` が許可リストにない	許可された channel を使用
400	`Invalid URL format`	`url` が有効な URL ではない	URL を修正して再送信
400	`events must be a string array`	`events` が文字列配列ではない	文字列配列を渡して再送信
400	`secret must be a string or null`	`secret` が string または null ではない	string または null を渡して再送信
400	`Webhook limit reached (max 20 per store)`	ストアの Webhook 数が 20 に達している	既存の Webhook を先に削除
401	`Missing merchantId in request context`	API Key 認証で merchant が解決されなかった	API Key ヘッダーと署名を確認
403	`Not authorized to manage webhooks for this store`	マーチャントがストアの `owner` または `admin` ではない	マーチャントのストアでの役割を確認
500	`Internal server error`	サーバ側の予期しない障害	指数バックオフでリトライ（5s 開始、最大 3 回）

⌘I