Webhook 通知
API で送信したメッセージが配信、既読、開封、クリック、バウンス、失敗になったときや、利用者が WhatsApp メッセージの配信を停止、再登録、または番号に送信したとき、Oblic はエンドポイントへイベントを POST します。
Webhook は webhooks:manage を持つ Owner または Admin キーで API から管理します。認証を参照してください。
エンドポイントの登録
- 名前
url- タイプ
- string
- 説明
必須:最大 2,048 文字の公開
httpsURL。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 | 条件 |
|---|---|---|
| 400 | INVALID_WEBHOOK_URL | URL が公開 https URL ではない |
| 400 | INVALID_EVENT_TYPE | イベント種別が下記一覧にない |
| 400 | WEBHOOK_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.failed | SMS が通信事業者へ渡された、配信された、未配信になった、または失敗した | 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日間の保持期間は延長されません。
失敗した配信
失敗した配信を、失敗時刻の新しい順にページ単位で返します。
- 名前
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、または接続を中断したエラーが入ります。
配信の再送
失敗した配信を再度キューに登録し、202 と状態 pending を返します。同じイベントと id が約1分以内に新たな署名で POST され、試行回数はリセットされます。
| 拒否ステータス | cd | 条件 |
|---|---|---|
| 404 | DELIVERY_NOT_FOUND | 組織に該当する配信がない |
| 409 | DELIVERY_NOT_FAILED | 配信が保留中または配信済み |
| 409 | WEBHOOK_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 になります。