Webhook概要

ZenFlip組織でイベントが発生した際にリアルタイム通知を受け取ります。WebhookURLの登録、署名の検証、リトライの処理方法を学びます。

On this page

Webhook概要

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

利用可能なイベント

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

イベント	トリガー
`publication.created`	新しいパブリケーションが作成された
`publication.converted`	PDF変換が完了（成功または失敗）
`publication.deleted`	パブリケーションが完全に削除された
`lead.captured`	閲覧者がリードキャプチャフォームを送信した
`team.member_joined`	チームメンバーが招待を承認した
`export.completed`	HTMLまたはSCORMエクスポートジョブが完了した

Webhookの登録

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

設定 > Webhookに移動します。
Webhookエンドポイントを追加をクリックします。
イベントを受信するURLを入力します（HTTPSが必須）。
サブスクライブするイベントを選択します（またはすべてを選択）。
保存をクリックします。

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 } } `

トップレベルフィールド

フィールド	型	説明
`id`	string	一意の配信ID（重複排除に使用）
`event`	string	イベントタイプ（例：`publication.created`）
`createdAt`	string	イベント発生時のISO 8601タイムスタンプ
`organizationId`	string	リソースを所有する組織のUUID
`data`	object	イベント固有のペイロード（イベントタイプにより異なる）

リクエストヘッダー

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

ヘッダー	説明
`X-ZenFlip-Event`	イベントタイプ（例：`publication.converted`）
`X-ZenFlip-Delivery-Id`	一意の配信ID（ペイロードの`id`と同じ）
`X-ZenFlip-Signature`	真正性検証のためのHMAC-SHA256署名
`Content-Type`	常に`application/json`
`User-Agent`	`ZenFlip-Webhooks/1.0`

署名検証

すべての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は配信失敗とみなし、指数バックオフでリトライします：

試行回数	前回の試行からの遅延
1	即座
2	1分
3	10分
4	1時間

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

冪等性

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

レスポンス要件

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

HTTP 2xxで応答する（200、201、202、204）ことで受信を確認します。
10秒以内に応答する。 時間のかかる処理が必要な場合は、Webhookを即座に確認してから非同期で処理してください。
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テストツールが含まれています：

設定 > Webhookに移動します。
エンドポイントの横にあるテストボタンをクリックします。
サンプルペイロードを送信するイベントタイプを選択します。
配信ログでリクエスト、レスポンス、エラーを確認します。

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例。

← Previous

Webhookイベントリファレンス