Webhook概要

Webhook概要

Webhookを使用すると、ZenFlip組織でイベントが発生したときにリアルタイムのHTTP POST通知をアプリケーションで受信できます。変更をポーリングする代わりに、URLを登録するとZenFlipが自動的にイベントペイロードをプッシュします。

利用可能なイベント

ZenFlipは以下のイベントタイプでWebhookを送信します：

Webhookの登録

ZenFlipダッシュボードでWebhookURLを設定します：

1. 設定 > Webhookに移動します。

2. Webhookエンドポイントを追加をクリックします。

3. イベントを受信するURLを入力します（HTTPSが必須）。

4. サブスクライブするイベントを選択します（またはすべてを選択）。

5. 保存をクリックします。

ZenFlipは各Webhookエンドポイントに署名シークレットを生成します。安全にコピーして保存してください --- Webhook署名の検証に必要です。

複数のWebhookエンドポイントを登録できます。各エンドポイントは異なるイベントタイプをサブスクライブできます。

ペイロード形式

すべてのWebhook配信はJSONボディを持つHTTP POSTリクエストです。ペイロード構造はすべてのイベントタイプで一貫しています：

`json { "id": "wh_del_550e8400-e29b-41d4-a716-446655440000", "event": "publication.converted", "createdAt": "2026-02-20T14:05:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "publicationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Product Catalog 2026", "versionNumber": 2, "status": "ready", "pageCount": 24 } } `

トップレベルフィールド

リクエストヘッダー

各Webhookリクエストには以下のカスタムヘッダーが含まれます：

署名検証

すべてのWebhookリクエストはエンドポイントの署名シークレットを使用してHMAC-SHA256で署名されています。リクエストがZenFlipからのものであり、改ざんされていないことを確認するために、必ず署名を検証してください。

署名は生のリクエストボディに対して計算されます：

` HMAC-SHA256(signing_secret, raw_request_body) `

結果はX-ZenFlip-Signatureヘッダーに16進エンコードされた文字列として送信されます。

検証例（Node.js）

`javascript const crypto = require("crypto");

function verifyWebhookSignature(rawBody, signature, secret) { const expected = crypto .createHmac("sha256", secret) .update(rawBody, "utf8") .digest("hex");

// タイミング攻撃を防ぐためにタイミングセーフな比較を使用 return crypto.timingSafeEqual( Buffer.from(signature, "hex"), Buffer.from(expected, "hex") ); }

// Expressルートハンドラー内 app.post("/webhooks/zenflip", express.raw({ type: "application/json" }), (req, res) => { const signature = req.headers["x-zenflip-signature"]; const secret = process.env.ZENFLIP_WEBHOOK_SECRET;

if (!verifyWebhookSignature(req.body, signature, secret)) { console.error("Invalid webhook signature"); return res.status(401).send("Invalid signature"); }

const event = JSON.parse(req.body); console.log("Received event:", event.event, event.id);

// イベントを処理...

res.status(200).send("OK"); }); `

重要： 署名検証のために生のリクエストボディにアクセスするには、express.raw()（または同等のもの）を使用してください。ボディをJSONとしてパースし再度文字列化すると、署名と一致しない異なるバイト列が生成される場合があります。

リトライポリシー

エンドポイントが10秒以内に2xxステータスコードで応答しない場合、ZenFlipは配信失敗とみなし、指数バックオフでリトライします：

合計4回の試行（初回1回 + リトライ3回）の後、配信はfailedとマークされます。配信履歴の確認と失敗の手動リトライはダッシュボードから行えます。

冪等性

各配信には一意のidがあります（X-ZenFlip-Delivery-Idヘッダーでも送信されます）。リトライやネットワークの問題により同じ配信が複数回受信された場合に備えて、このIDを使用してイベントの重複を排除してください。

レスポンス要件

Webhookエンドポイントは以下の要件を満たす必要があります：

1. HTTP 2xxで応答する（200、201、202、204）ことで受信を確認します。

2. 10秒以内に応答する。 時間のかかる処理が必要な場合は、Webhookを即座に確認してから非同期で処理してください。

3. POSTリクエストを受け付ける（Content-Type: application/json）。

`javascript // 推奨パターン：即座に確認し、非同期で処理 app.post("/webhooks/zenflip", express.raw({ type: "application/json" }), (req, res) => { // まず署名を検証 // ...

// 受信を即座に確認 res.status(200).send("OK");

// 非同期で処理 const event = JSON.parse(req.body); processWebhookEvent(event).catch(console.error); }); `

Webhookのテスト

ZenFlipダッシュボードにはWebhookテストツールが含まれています：

1. 設定 > Webhookに移動します。

2. エンドポイントの横にあるテストボタンをクリックします。

3. サンプルペイロードを送信するイベントタイプを選択します。

4. 配信ログでリクエスト、レスポンス、エラーを確認します。

ngrokなどのツールを使用して、ローカル開発サーバーをインターネットに公開してテストすることもできます：

`bash

ngrokを起動してローカルサーバーのパブリックURLを作成

ngrok http 3000

生成されたURL（例：https://abc123.ngrok.io/webhooks/zenflip）を

ZenFlipダッシュボードのWebhookエンドポイントとして使用

`

配信履歴

すべてのWebhook配信はログに記録され、ダッシュボードからアクセスできます。各エントリには以下が表示されます：

• イベントタイプと配信ID

• タイムスタンプ

• エンドポイントからのHTTPレスポンスステータス

• レスポンスボディ（最初の1,000文字）

• 試行回数

• 現在のステータス：pending、success、またはfailed

次のステップ

• [Webhookイベントリファレンス](/docs/webhooks-events) --- 各イベントタイプの詳細なペイロードスキーマとJSON例。