Webhook 通知

API で送信したメッセージが配信、既読、開封、クリック、バウンス、失敗になったときや、利用者が WhatsApp メッセージの配信を停止、再登録、または番号に送信したとき、Oblic はエンドポイントへイベントを POST します。


POST/external/v1/webhooks

エンドポイントの登録

  • 名前
    url
    タイプ
    string
    説明

    必須:最大 2,048 文字の公開 https URL。localhost と IP アドレスは拒否され、ホスト名がプライベートまたは内部アドレスに解決されると配信に失敗します。

  • 名前
    eventTypes
    タイプ
    string[]
    説明

    送信するイベント種別を最大 20 個指定します。省略または空の場合は whatsapp.inbound 以外の全種別が対象です。この種別には利用者が書いた内容が含まれるため、明示したエンドポイントにのみ送られます。

エンドポイントの登録

curl -X POST https://api.oblic.app/external/v1/webhooks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://hooks.example.com/oblic",
    "eventTypes": ["email.delivered", "email.bounced", "sms.delivered", "whatsapp.read"]
  }'

レスポンス

{
  "status": "success",
  "data": {
    "id": "whk_0c6f1e2d3b4a59687766554433221100",
    "url": "https://hooks.example.com/oblic",
    "eventTypes": ["email.delivered", "email.bounced", "sms.delivered", "whatsapp.read"],
    "secret": "whsec_…"
  },
  "errors": null
}
  • シークレットはこのエンドポイントへの各配信に署名します(後述)。Oblic が生成し、エンドポイントに関する各レスポンスに含めます。シークレットと取得に使うキーはサーバーに保管してください。変更するにはエンドポイントを削除し、同じ URL を再登録します。
  • 登録済みの URLは既存エンドポイントをそのまま返し、イベント種別とシークレットは変更しません。
  • 組織あたり最大 10 エンドポイントで、各 URL は一度だけ登録できます。
拒否ステータスcd条件
400INVALID_WEBHOOK_URLURL が公開 https URL ではない
400INVALID_EVENT_TYPEイベント種別が下記一覧にない
400WEBHOOK_LIMIT組織に既に 10 エンドポイントある

イベント種別

種別名送信タイミングdata
email.deliveredメールが受信者のメールサーバーに到達したmessageId, recipients
email.delivery_delayed配信が遅延し、試行が継続しているmessageId, recipients, delayType
email.bouncedメールがバウンスしたmessageId, recipients, bounceType, bounceSubType
email.complained受信者が迷惑メールとして報告したmessageId, recipients, feedbackType
email.openedメールが開封されたmessageId, recipients
email.clickedメール内のリンクがクリックされたmessageId, recipients, link
email.suppressed配信停止または抑止リストにより受信者が除外されたmessageId、recipients(除外された受信者)、reason:unsubscribed または suppression_list
email.failedメールを送信できなかったmessageId、recipients、failureCode:SES のエラー、またはアカウントのメール停止中の EMAIL_SUSPENDED
sms.sent, sms.delivered, sms.undelivered, sms.failedSMS が通信事業者へ渡された、配信された、未配信になった、または失敗したmessageId, status, failureCode, occurredAt, segments
whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failedメッセージが送信、配信、既読、または失敗になったmessageId, status, failureCode, occurredAt
whatsapp.opted_out番号がマーケティングメッセージを配信停止したnumber、source:keyword、button または meta_131050、occurredAt
whatsapp.opted_in番号が再登録したnumber、source:keyword または community_opt_in、occurredAt
whatsapp.inbound利用者が番号へメッセージを送ったfrom、messageId(WhatsApp 独自の ID)、type、text、receivedAt
  • messageId は送信レスポンスの msg_… ID で、イベントとメッセージを関連付けます。ただし whatsapp.inbound は例外です。
  • metadata はメール、SMS、WhatsApp の各メッセージイベントに、送信時のデータまたは {} として含まれます。メタデータを参照してください。配信停止、登録、whatsapp.inbound には含まれません。
  • メールイベントは API 経由のメールが対象で、キャンペーンは対象外です。
  • メールの recipients はイベント対象の受信者です。ただし email.opened と email.clicked は送信先全件を列挙します。メールでは誰が開いたか特定できないためです。
  • text は写真、文書、その他メディアの whatsapp.inbound では省略されます。

イベント本体

各配信は一つのイベントを JSON 本文に持つ POST リクエストです。

イベント例

{
  "id": "evt_5d0b8e2f9c1a4d7e8b6f3a2c1d0e9f87",
  "type": "email.bounced",
  "createdAt": "2026-10-24T10:15:30.123456Z",
  "account": { "id": "ORG000R7ZM4Q2VXH00" },
  "data": {
    "messageId": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60",
    "recipients": ["asha@example.org"],
    "bounceType": "Permanent",
    "bounceSubType": "General",
    "metadata": { "orderId": "1042" }
  }
}
  • id はイベントの ID で、同じイベントの配信では変わりません。重複排除に使ってください。
  • account は元のメッセージの組織で、その id と、サブアカウントの場合は指定した externalId を含みます。
  • 値のないフィールドは省略されます。

配信の検証

各配信には Oblic-Signature ヘッダーがあり、署名と経過時間を確認できます。イベントの id でも重複排除してください。有効な署名でも一意の配信とは限りません。

Oblic-Signature: t=1761300930,v1=5b3f…
  • t は署名時刻を表す Unix 秒です。
  • v1 は t、ピリオド、生のリクエスト本文の HMAC-SHA256 です。エンドポイントの完全なシークレット(whsec_ を含む)をキーにし、小文字の16進数で表します。

JSON を解析する前に受信したままの本文から同じ署名を計算し、定時間で比較し、現在時刻から離れすぎた t を拒否します。欠落または不正なヘッダーは検証失敗です。各試行は固有の t で再署名されるため、再試行にも5分の許容幅を適用できます。

署名の検証

import crypto from 'node:crypto'

// header: the Oblic-Signature header; body: the raw body as a string.
export function verified(header, body, secret) {
  if (typeof header !== 'string') return false
  const pairs = header.split(',').map((field) => field.split('='))
  if (pairs.some(([name, ...value]) => !name || value.length !== 1)) return false
  const fields = Object.fromEntries(pairs)
  if (Object.keys(fields).length !== pairs.length) return false
  const t = fields.t
  const signature = fields.v1
  if (!t || /[^0-9]/.test(t)) return false
  if (signature?.length !== 64 || /[^0-9a-f]/.test(signature)) return false
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${body}`)
    .digest()
  return crypto.timingSafeEqual(expected, Buffer.from(signature, 'hex'))
}

コードの確認用:シークレット whsec_test、t が 1700000000、本文が {"a":1} の場合、v1 は 38877139021993b830af32feea6e18a8da83eb2f6e49ee50bd9e4cf4ca4d3789 です。

配信には Content-Type: application/json; charset=utf-8 と User-Agent: Oblic-Webhooks/1 も含まれます。


配信と再試行

  • 10秒以内に任意の 2xx を返し、処理はその後で行ってください。それ以外の応答、追跡されないリダイレクト、時間内の応答なしはいずれも失敗です。
  • 失敗した試行は再実行されます。30秒後、その後1、2、4、8、16、32分後、以降は毎時で、約8時間に15回試行します。最後も失敗すると失敗扱いになり、最初のキュー登録から1週間、再送用に保持されます。
  • 同じイベントが複数回届く場合があります。再送や応答の消失時が該当し、発生順に届くとも限りません。id で重複を排除し、順序には occurredAt または createdAt を使ってください。
  • サブアカウントのイベントは専用エンドポイントがあればそこへ、なければ親のエンドポイントへ送られます。一つでも専用エンドポイントを登録すると、購読種別にかかわらず全イベントが専用側だけに送られます。

これらは予定された待ち時間で、配信期限の保証ではありません。配信ワーカーの有効化が必要で、キューの滞留や遅いエンドポイントで実行が遅れることがあります。再送しても最初のキュー登録から7日間の保持期間は延長されません。


GET/external/v1/webhooks/deliveries

失敗した配信

失敗した配信を、失敗時刻の新しい順にページ単位で返します。

  • 名前
    webhookId
    タイプ
    string
    説明

    このエンドポイントの配信のみです。

  • 名前
    limit
    タイプ
    integer
    説明

    件数は1~100で、既定値は25です。

  • 名前
    cursor
    タイプ
    string
    説明

    前ページの next。ページネーションを参照してください。

レスポンス

{
  "status": "success",
  "data": {
    "deliveries": [
      {
        "id": 48213,
        "webhookId": "whk_0c6f1e2d3b4a59687766554433221100",
        "status": "failed",
        "attempts": 15,
        "lastError": "HTTP 503",
        "createdAt": "2026-10-23T22:01:04Z",
        "deliveredAt": null,
        "failedAt": "2026-10-24T06:09:51Z",
        "event": { "id": "evt_5d0b8e2f9c1a4d7e8b6f3a2c1d0e9f87", "type": "email.bounced", "createdAt": "2026-10-23T22:01:04.512310Z", "account": { "id": "ORG000R7ZM4Q2VXH00" }, "data": { "messageId": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60", "recipients": ["asha@example.org"], "bounceType": "Permanent", "bounceSubType": "General" } }
      }
    ],
    "next": null
  },
  "errors": null
}

lastError は最後の失敗理由です。HTTP と応答ステータス、非公開アドレスを表す refused url、または接続を中断したエラーが入ります。


POST/external/v1/webhooks/deliveries/{deliveryId}/replay

配信の再送

失敗した配信を再度キューに登録し、202 と状態 pending を返します。同じイベントと id が約1分以内に新たな署名で POST され、試行回数はリセットされます。

拒否ステータスcd条件
404DELIVERY_NOT_FOUND組織に該当する配信がない
409DELIVERY_NOT_FAILED配信が保留中または配信済み
409WEBHOOK_NOT_FOUNDエンドポイントが削除され、送信先がない

エンドポイントの管理

メソッドパス動作
GET/external/v1/webhooks組織のエンドポイントとそのシークレット
GET/external/v1/webhooks/{webhookId}単一のエンドポイント
PUT/external/v1/webhooks/{webhookId}登録時と同じ指定方法で url と eventTypes を変更し、シークレットは維持する
DELETE/external/v1/webhooks/{webhookId}そのエンドポイントへの配信を停止する

組織が所有しないエンドポイントは 404 WEBHOOK_NOT_FOUND、別のエンドポイントの URL への変更は 400 WEBHOOK_EXISTS になります。

このページは役に立ちましたか?