メインコンテンツへスキップ
ジャーニーWebhookは、ジャーニーステップからサーバーまたは公開アクセス可能なエンドポイントへHTTPリクエストを送信します。HTTPメソッド、URL、ヘッダー、ボディコンテンツを設定できます。リクエストはLiquid構文を使用してユーザー固有のデータでパーソナライズでき、ジャーニーイベントをCRM、分析プラットフォーム、またはカスタムバックエンドとリアルタイムで同期できます。

​
要件

  • アクセスするにはOneSignal営業チームにお問い合わせください。
  • URLまたはIPアドレスは有効で、HTTPまたはHTTPS経由でアクセス可能である必要があります。
  • エンドポイントは公開ルーティング可能でなければなりません——ファイアウォールの背後やlocalhostにはありません。
  • ドメインには有効なトップレベルドメイン（.com、.org、.netなど）が必要です。
ジャーニーWebhookはOneSignal APIを呼び出すことができません。外部システムへのデータ送信専用に設計されています。

​
セットアップ

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

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

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

​
Webhookのテスト

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

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

すべてのWebhookフィールドは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をテストしてください。 エンドポイントはジャーニーが生成するイベントのボリュームを処理できる必要があります。アプリのメッセージ送信量を確認して、APIに必要なスループットを見積もってください。

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

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

​
信頼性のベストプラクティス

  • まず自分のサーバーを経由してルーティングし、サードパーティサービスに直接接続しないでください。これにより、ログ記録、認証、スロットリング、キューイングを制御できます。サードパーティサービスはボリュームスパイク時にリクエストをレート制限またはブロックする可能性があり、OneSignalはこれらの制限を管理しません。
  • バーストに備えてください。 Webhookの実行はユーザーがステップに到達するとすぐに発生します。多くのユーザーが一度にWebhookステップに到達すると、OneSignalはレート制限なしでHTTPリクエストのバーストを送信します。Webhookを確実に取り込み、レート制限またはバッチ処理を適用し、サードパーティサービスへのリクエストを適切にルーティングできる軽量APIレイヤーまたはキューイングプロキシの構築を検討してください。
  • サードパーティAPIの制限を確認してください。 Slack、Twilio、Segmentなどの人気ツールはパブリックHTTP APIを提供していますが、独自のレート制限、認証要件、エラー処理があります。直接接続する前にドキュメントを確認してください。

​
Webhookを保護する

リクエストがOneSignalから送信され、改ざんされていないことを確認するには：
  • HMAC署名：Webhook設定に共有シークレットを含めます。OneSignalはHMACヘッダーで各リクエストに署名し、サーバーがペイロードを処理する前に検証できます。
  • カスタム認証トークン：カスタム認証ヘッダー（例：Authorization: Bearer YOUR_SECRET_TOKEN）を追加し、リクエストを受け入れる前にサーバー側で検証します。

​
よくある質問

​
WebhookでOneSignal APIを呼び出せますか？

いいえ。ジャーニーWebhookは外部システムへのデータ送信専用に設計されています。OneSignal APIを呼び出すことはできません。ジャーニーイベントに基づいてOneSignalデータを更新するには、Webhookを自分のサーバー経由でルーティングし、サーバーからOneSignal APIを呼び出してください。

​
なぜWebhookが自動的に無効化されたのですか？

OneSignalは、継続的に失敗するWebhookをそれ以上の問題を防ぐために無効にします。ログタブでエラーの詳細（ステータスコード、レスポンスボディ）を確認し、根本原因を修正し、再度有効にする前にWebhookをテストしてください。一般的な原因には、エンドポイントのダウンタイム、認証エラー、レート制限があります。

​
Webhookイベントの重複を排除するにはどうすればよいですか？

event.id値（ヘッダーまたはリクエストボディで利用可能）を使用してユニークなイベントを識別します。処理済みのイベントIDをサーバーに保存し、重複をスキップします。再試行が同じイベントを複数回配信する場合、これは特に重要です。

​
OneSignalはWebhookリクエストをレート制限しますか？

いいえ。OneSignalはユーザーがステップに到達するとすぐに、レート制限なしでWebhookリクエストを送信します。多くのユーザーが一度にWebhookステップに到達すると、エンドポイントはリクエストのバーストを受け取ります。ピークボリュームを処理できるようにエンドポイントを構築するか、キューイングプロキシを使用してリクエストをバッファリングおよびバッチ処理してください。

​
Journeyを起動せずにWebhookをテストできますか？

はい。Webhook設定のテストボタンを使用してサンプルリクエストを送信します。タグはテストリクエストでは利用できません——完全な検証のためには、ライブジャーニーでテストサブスクリプションを使用してください。

​
関連ページ

ジャーニー概要

ジャーニーの紹介とマルチチャネルワークフローの仕組み。

ジャーニーアクション

待機ステップ、分岐ロジック、タイムウィンドウ、分割パスを追加します。

Liquid構文

OneSignalメッセージとWebhookのLiquidテンプレートの完全リファレンス。

メッセージパーソナライゼーション

タグ、Liquid、動的コンテンツを含むすべてのパーソナライゼーション方法の概要。