PDF生成完了・ダウンロード・期限切れのイベントを、登録URLにPOST通知。HMAC-SHA256署名と自動リトライ(60秒後・5分後の最大2回)付きで、業務システムへの組み込みが安全。
サーバーから能動的に通知が届くため、クライアントは定期的にAPIを叩く必要がありません。レイテンシも最小。
X-Webhook-Signature ヘッダに sha256 のHMACが付与されます。Webhookシークレットで検証して安全に処理。
hooks.slack.com を含むURLを登録すると、Block Kit形式のリッチ通知に自動変換。設定なしで使えます。
| Webhookを使う | ポーリングする | |
|---|---|---|
| 完了検知のレイテンシ | イベント発生後すぐに送信 | ポーリング間隔次第 |
| サーバー負荷 | 完了時のみ1リクエスト | 全アイテム×ポーリング回数 |
| 受信側の準備 | 公開エンドポイントが必要 | クライアントだけで完結 |
| Slack連携 | URLを登録するだけ | 別途実装が必要 |
// Register a webhook endpoint
await fetch("/api/webhooks", {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://your-app.example.com/hooks/pdf",
events: ["pdf.generated", "pdf.expired"],
}),
});
// The response's data.secret is returned only on creation — store it.
// Verify the X-Webhook-Signature header on incoming requests:
// sha256=HMAC_SHA256(payload, webhook_secret)
//
// 5xx, timeouts and connection errors are retried after 60s and 5m
// (3 attempts in total, including the first).
// Slack incoming-webhook URLs auto-receive Block Kit payloads.