POST /api/webhooks
完了タイミングをプッシュで受け取る
PDF生成完了・ダウンロード・期限切れ・バッチ完了の4イベントを、登録URLにPOST通知。HMAC-SHA256署名と自動リトライ（60秒→5分→15分）付きで、業務システムへの組み込みが安全。
この機能の主なポイント
1
ポーリング不要
サーバーから能動的に通知が届くため、クライアントは定期的にAPIを叩く必要がありません。レイテンシも最小。
2
署名検証で改ざん防止
X-Webhook-Signature ヘッダに sha256 のHMACが付与されます。Webhookシークレットで検証して安全に処理。
3
Slack URLを自動検出
hooks.slack.com で始まるURLを登録すると、Block Kit形式のリッチ通知に自動変換。設定なしで使えます。
使う場合 vs 使わない場合
| Webhookを使う | ポーリングする | |
|---|---|---|
| 完了検知のレイテンシ | 数秒以内 | ポーリング間隔次第 |
| サーバー負荷 | 完了時のみ1リクエスト | 全アイテム×ポーリング回数 |
| 受信側の準備 | 公開エンドポイントが必要 | クライアントだけで完結 |
| Slack/Discord連携 | URLを登録するだけ | 別途実装が必要 |
実装例
// Register a webhook endpoint
await fetch("/api/webhooks", {
method: "POST",
headers: { "Authorization": `Bearer ${API_KEY}` },
body: JSON.stringify({
url: "https://your-app.example.com/hooks/pdf",
events: ["pdf.generated", "batch.completed"],
}),
});
// Verify the X-Webhook-Signature header on incoming requests:
// sha256=HMAC_SHA256(payload, webhook_secret)
//
// 5xx responses are retried with backoff: 60s → 5m → 15m (3 tries total).
// Slack incoming-webhook URLs auto-receive Block Kit payloads.