メインコンテンツへスキップ
ジャーニーWebhookを使用すると、顧客のライフサイクルの正確なタイミングで、OneSignalジャーニーからサーバー、またはインターネットアクセス可能な任意のサービスにHTTPリクエストを送信できます。HTTPメソッド、URL、ヘッダー、およびボディコンテンツを構成して、統合要件に一致させます。リクエストはユーザー固有のデータで動的にパーソナライズでき、Webhookをマーケティングスタックの残りの部分とジャーニーを同期する強力な方法にします。

​
要件

イベントを送信する前に、次のことを確認してください：
  • アクセスするには営業チームにお問い合わせください。
  • URL/IPアドレスが有効で、HTTPまたはHTTPS経由で到達可能です。
  • エンドポイントは公開ルーティング可能です（つまり、ファイアウォールの背後やlocalhostにはありません）。
  • ドメインには有効なトップレベルドメイン（例：.com、.org、.net）が必要です。
  • ジャーニーWebhookはOneSignal APIを呼び出すために使用できません。

​
セットアップ

ジャーニーが作成されたら、次の手順に従います：
  1. OneSignalダッシュボードでデータ > Webhookに移動します。
  2. クリックして新しいWebhookを作成します。
  3. 次を定義します：
    • HTTPメソッド（通常は POST)
    • ターゲットURL
    • カスタムヘッダー（例：認証用）
    • ボディコンテンツ（プレーンテキストまたはJSON、オプションでLiquidを使用）

Webhook設定画面

​
許可されていないヘッダー

次のヘッダーを設定することはできません：
  • content-length
  • referer
  • metadata-flavor
  • x-google-metadata-request
  • host
  • x-onesignalで始まるすべてのヘッダー

​
Webhookのテスト

curlなどのツールを使用して、エンドポイントを手動でテストすることもできます：
bash
curl -X POST https://yourserver.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "abc123" }'
ジャーニーに追加する前に、エンドポイントが到達可能で機能していることを検証するのに役立ちます。

​
パーソナライゼーション

すべてのWebhookフィールドはLiquid構文をサポートしており、ユーザーとサブスクリプションデータをリクエストに動的に挿入できます。 ボディの例： 
{
  "user_id": "{{ user.onesignal_id }}",
  "email": "{{ user.tags.email }}",
  "language": "{{ user.language }}"
}
詳細については、Liquid構文の使用ガイドを参照してください。

​
ユーザーデータリファレンス

userオブジェクトの次のプロパティは、Liquid構文を介してWebhookフィールドで利用できます：
プロパティタイプ使用方法テストで利用可能？
OneSignal IDString{{ user.onesignal_id }}✅
External IDString{{ user.external_id }}✅
TagsObject{{ user.tags.your_tag_key_here }}❌
LanguageString{{ user.language }}✅
タグは、アクティブなジャーニー外でWebhookをテストするときには使用できません。ライブに移行する前に動作を検証するには、テストサブスクリプションを使用してください。

​
ジャーニーにWebhookを追加する

  1. Webhookを作成してテストした後、ジャーニーを開きます。
  2. 必要な場所にWebhookステップを追加します。
  3. 以前に構成したWebhookを選択します。
ユーザーがそのステップに到達するたびに、パーソナライズされたデータでWebhookが起動します。

ジャーニー内のWebhookステップ

​
デバッグとログ

​
Webhook統計

Webhookの統計タブに移動して、Webhookのパフォーマンスを表示します。これには次のものが含まれます：
  • 送信されたイベントの合計
  • レスポンス時間のトレンド
  • ステータスコードの分布

Webhookレポートページ

​
ログタブ

より詳細なインサイトについては、ログタブに次が表示されます：
  • 最近のリクエスト/レスポンスデータ
  • ステータスコードとエラーメッセージ
  • ヘッダーとペイロード（該当する場合）

Webhookログページ

​
再試行ロジックと無効化動作

OneSignalは、回復可能なエラー（例：429 Too Many Requests）のために失敗したWebhookリクエストを再試行します。再試行は、遅延を増やしながら行われます。 再試行が繰り返し失敗すると、Webhookは永久に失敗としてマークされ、これ以上の試行は行われません。

​
自動無効化

Webhookが一貫して失敗する場合、OneSignalはそれ以上の問題を防ぐためにそれを無効にします。管理者は、Webhookが無効になる前と後に、メールアラートとダッシュボードバナーを受け取ります。これが発生した場合は、再度有効にする前に、Webhookのトラブルシューティング、修正、テストに時間を費やしてください。 Webhookを取り込むAPIが、メッセージ送信によって生成されるイベントのボリュームを処理できることが重要です。アプリによって生成されるメッセージ送信のボリュームを確認すると、APIに必要なパフォーマンスが反映されます。

​
パフォーマンスガイダンス

  • 遅いまたは過負荷のエンドポイント（特に429レスポンスの場合）は、無効化をトリガーする可能性があります。
  • APIは、タイムアウトを回避するために、イベントを迅速に記録し、追加の処理を延期する必要があります。
  • ボリュームはユーザーアクティビティに応じてスケーリングされます—エンドポイントがこのスループットを処理できることを確認してください。
  • 受信イベントの重複を排除するには、event.id値（ヘッダーまたはボディで利用可能）を使用します。

​
成功のためのヒント

  • Webhookを最初に自分のサーバーに接続し、サードパーティサービスに直接接続しないでください。
    • OneSignal WebhookはすべてのパブリックAPIを呼び出すことができますが、自分のサーバーを経由することで、より多くの制御が得られます。
    • デバッグ、ログの追加、認証の処理、必要に応じたリクエストの調整またはキューイングが容易です。
    • サードパーティサービスは、ボリュームが急増した場合にリクエストをレート制限またはブロックする可能性があり、OneSignalはこれらの制限を管理しません。
  • Webhook実行は、ユーザーがジャーニーのそのステップに到達するとすぐに発生します。
    • 多くのユーザーが一度にWebhookステップに到達すると、OneSignalはレート制限なしでHTTPリクエストのバーストを送信します。
    • これにより、外部サービスを簡単に圧倒したり、レート制限をトリガーしたり、予期しない料金が発生したりする可能性があります。
    • 次のことができる軽量APIレイヤーまたはキューイングプロキシを構築することを検討してください：
      • Webhookを確実に取り込む
      • レート制限またはバッチ処理を適用する
      • サードパーティサービスへのリクエストを正常にルーティングする
  • サードパーティAPIは慎重に使用してください：
    • ほとんどの人気のあるツール（例：Slack、Twilio、Segment）は、パブリックHTTP APIを提供しています。
    • レート制限、認証要件、エラー処理戦略を確認してください。
    • ドキュメントでコード例を検索して、Webhookリクエストがどのようなものかを確認してください。

​
Webhookを保護する

リクエストがOneSignalから送信され、改ざんされていないことを確認するには：
  • 共有シークレットを使用してHMAC署名ヘッダーを使用する
  • ヘッダーにカスタム認証トークンを追加し、サーバー側で検証する

​
関連リンク：