Webhooks

​

Webhook の仕組み

• 各 Webhook は、1 つのテーブルと 1 つ以上のトリガー操作を監視します。
• 条件に一致する変更が発生すると、Alforse は配信をキューに入れ、非同期で送信します。通常は数瞬で届きます。
• 各配信には、その Webhook 固有のシークレットで署名が付くため、エンドポイント側でリクエストが Alforse から送られたことを確認できます。
• 本文は、レコードが変更されたことの通知です。対応する前に、APIキーを使って現在のレコードを取得してください。

​

購読できるテーブル

​

Webhook を設定する

​

配信の内容

​

本文

{
  "type": "UPDATE",
  "table": "salesOrder",
  "companyId": "abc123",
  "record": { "id": "...", "salesOrderId": "SO000042", "status": "To Ship and Invoice" }
}

​

ヘッダー

​

配信と再試行

• 10 秒以内に成功ステータスを返さない。
• 5xx または 429 を返す。

• その他の 4xx レスポンスは、その変更の配信を終了します。
• 3xx レスポンスは、Alforse がリダイレクトに従わないため、失敗として扱われます。最終的な URL を設定してください。
• 拒否されたアドレスへの配信は再試行されません。

​

エンドポイントを設計する

• 重複を想定してください。 最初の試行をすでに処理した後で、再試行が届くことがあります。重複排除は、type と record.id の組み合わせではなく x-omeriva-webhook-event で行ってください。同じレコードに対する別々の変更が、これらの値を共有するためです。
• 障害後は照合してください。 破棄された変更は再送されません。すべてのイベントを処理する必要がある場合は、エンドポイントの停止後に API を照会して追いつかせてください。

​

配信を検証する

1. パースする前に、生の本文を取得します。JSON をパースして再シリアライズするとバイト列が変わり、署名が一致しなくなります。
2. HMAC を計算し、v1= の後ろの値と、定数時間の比較で照合します。
3. 自分の時計から 5 分以上ずれているタイムスタンプは拒否します。これにより、傍受されたリクエストが再生されるのを防げます。再試行は毎回新しいタイムスタンプで再署名されるため、正当な再試行は通ります。

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyAlforseSignature(
  rawBody: string,
  signatureHeader: string,
  timestampHeader: string,
  secret: string,
  toleranceSeconds = 300
) {
  const timestamp = Number(timestampHeader);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const received = signatureHeader.replace(/^v1=/, "");
  return (
    received.length === expected.length &&
    timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
}

​

トラブルシューティング

​

関連項目