Webhook

Webhookを使うと、アプリケーションがPDFSimpleからのリアルタイムイベント通知を受け取れます。APIをポーリングしてジョブの状態を確認する代わりに、エンドポイントを登録しておけば、イベント発生時にPDFSimpleが署名付きペイロードをそこにPOSTします。

Webhookの設定

1. ダッシュボード → Webhookに移動し、「エンドポイントを追加」をクリックします。
2. HTTPSエンドポイントURLを入力します（例：https://yourapp.com/webhooks/pdfsimple）。
3. 受け取りたいイベント（job.completed、job.failedなど）を選択します。
4. 「作成」をクリックします。固有のWebhookシークレットが表示されるので、その場ですぐにコピーしてください — 表示されるのは一度だけです。
5. シークレットはアプリケーションの環境変数などに安全に保管してください。

Webhookイベント

• job.completed — PDF処理ジョブが正常に完了しました。ペイロードにはジョブID、出力ファイルのURL、メタデータが含まれます。
• job.failed — ジョブでエラーが発生しました。ペイロードにはエラーメッセージが含まれます。

Webhook署名の検証

すべてのWebhookリクエストには、Webhookシークレットを使って計算された生のリクエストボディのHMAC-SHA256署名を含むX-PDFSimple-Signatureヘッダーが付与されます。ペイロードを処理する前に、必ずこの署名を検証してください。

const crypto = require('crypto');

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

再試行と配信保証

エンドポイントが30秒以内に2xxレスポンスを返さない場合、PDFSimpleは指数バックオフにより最大5回、30日間にわたって配信を再試行します。Webhookイベントは30日間保持されます。