メインコンテンツへスキップ

​
概要

WebプッシュWebhookを使用すると、ユーザーがプッシュ通知とやり取りするたびにリアルタイムHTTP POST通知を受信できます。通知が表示、クリック、または却下されると、OneSignalは通知データとカスタムパラメーターを指定されたWebhook URLに自動的に送信します。
JourneyのWebhookについては、Journey Webhookページを参照してください。
主な利点：
  • リアルタイムで通知エンゲージメントを追跡
  • ユーザーインタラクションに基づいて自動ワークフローをトリガー
  • 通知データを分析プラットフォームと同期
  • 通知イベントのカスタムビジネスロジックを実装

​
ブラウザーサポート

ブラウザープラットフォームサポート利用可能なWebhookイベント
ChromemacOS、Windows、Androidすべてのイベント（表示、クリック、却下）
FirefoxmacOS、Windows、Android表示とクリックイベント
Safariサポートされていませんなし

​
利用可能なWebhookイベント

​
notification.willDisplay

ユーザーの画面に通知が表示された直後にトリガーされます。 ユースケース： 配信率の追跡、インプレッションデータのログ、フォローアップキャンペーンのトリガー

​
notification.clicked

ユーザーが通知本文またはアクションボタンをクリックしたときにトリガーされます。 ユースケース： エンゲージメント率の追跡、コンバージョンイベントのトリガー、特定のコンテンツへのユーザーのリダイレクト

​
notification.dismissed

ユーザーが通知をアクティブに却下したとき、または自動的に期限切れになったときにトリガーされます。 ブラウザーサポート： Chromeのみ ユースケース： 却下率の追跡、通知タイミングの最適化、通知コンテンツのA/Bテスト 重要： 通知本文またはアクションボタンをクリックしても、却下Webhookはトリガーされません。

​
セットアップ方法

  • ダッシュボード設定（ほとんどのユーザーに推奨）
  • カスタムコード統合
1

OneSignalダッシュボードでSettings > Webに移動します
2

「Enable webhooks」トグルを有効にします
3

追跡したい各イベントのWebhook URLを入力します

OneSignalダッシュボード設定でWebhookを有効化

Webhook URLはHTTPSであることを確認してください（Chromeのセキュリティポリシーで必須）。

​
CORS設定

cors設定は、Webhookエンドポイントが受信するヘッダーとデータを決定します：
  • cors: false（推奨）： よりシンプルなセットアップ、サーバーでのCORS設定は不要
  • cors: true： 追加のヘッダーを提供しますが、サーバーでのCORSサポートが必要
cors: trueを使用するタイミング：
  • Content-Type: application/jsonヘッダーが必要
  • イベントの識別を容易にするためにX-OneSignal-Eventヘッダーが必要
  • サーバーがすでに非シンプルリクエストのCORSをサポートしている

​
Webhookリクエスト形式

​
標準リクエスト（cors: false）

Webhookエンドポイントは、次のペイロード構造でPOSTリクエストを受信します： 
{
  "event": "notification.clicked",
  "notificationId": "ed46884e-0e3f-4373-9e11-e28f27746d3d",
  "heading": "Your notification title",
  "content": "Your notification message",
  "additionalData": {
    "userId": "12345",
    "campaignId": "summer-sale",
    "customField": "customValue"
  },
  "actionId": "buy-now-button",
  "url": "https://yoursite.com/product/123"
}

​
拡張リクエスト（cors: true）

上記と同じペイロードに加えて、次の追加ヘッダーが含まれます： 
Content-Type: application/json
X-OneSignal-Event: notification.clicked

​
ペイロードフィールドリファレンス

フィールドタイプ説明常に存在
eventstringWebhookをトリガーしたイベントタイプ✅
notificationIdstring一意のOneSignal通知識別子✅
headingstring通知タイトル提供された場合のみ
contentstring通知メッセージ本文提供された場合のみ
additionalDataobject通知と共に送信されるカスタムデータ提供された場合のみ
actionIdstringクリックされたアクションボタンのID（空文字列 = 通知本文がクリックされた）クリックイベントのみ
urlstring通知の起動URL提供された場合のみ
subscriptionIdstringOneSignalユーザー/サブスクリプションIDCORS有効時のみ

​
実装のベストプラクティス

​
Webhookエンドポイントの要件

セキュリティ：
  • HTTPS URLのみを使用（HTTP URLはChromeによってブロックされます）
  • Webhookエンドポイントに適切な認証/検証を実装
  • 大量の通知を処理するためにレート制限を検討
応答要件：
  • 処理が成功した場合はHTTP 200ステータスを返す
  • タイムアウトを避けるために10秒以内に応答
  • 重複するWebhook呼び出しを適切に処理（冪等性を実装）

​
エラーハンドリング

// Example webhook endpoint (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
  try {
    const { event, notificationId, additionalData } = req.body;

    // Validate required fields
    if (!event || !notificationId) {
      return res.status(400).json({ error: 'Missing required fields' });
    }

    // Process the webhook data
    processNotificationEvent(req.body);

    // Always respond with 200 OK
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Webhook processing error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

​
よくある問題と解決策

​
Webhookが発火しない

考えられる原因：
  • OneSignal初期化を含むすべてのページにWebhookコードが存在しない
  • Webhookコードが追加された後、ユーザーがWebhookコードを含むページにアクセスしていない
  • HTTPS要件が満たされていない
  • サーバーが200以外のステータスコードを返している
解決策： 通知がアクティブなすべてのページのOneSignal initコードにWebhook設定が含まれていることを確認してください。

​
Webhookでデータが欠落

原因： Webhookは、Webhook設定がアクティブなページにアクセスするユーザーのイベントのみを追跡します。 解決策： 特定のランディングページだけでなく、OneSignalを含むすべてのページにWebhookコードをデプロイしてください。

​
重複するWebhook呼び出し

原因： ネットワークの問題やブラウザーの動作により、重複するリクエストが発生する可能性があります。 解決策： notificationIdフィールドを使用して冪等性を実装し、イベントの重複を排除してください。

​
Webhookの制限事項

  • イベントごとに1つのWebhook URL： 同じイベントタイプに複数のWebhook URLを設定することはできません
  • HTTPSのみ： ブラウザーのセキュリティ制限により、HTTP URLは機能しません
  • Chromeのみの却下追跡： notification.dismissedイベントはChromeでのみ機能します
  • ページ依存性： 追跡が機能するには、ユーザーがWebhookコードがアクティブなページにアクセスする必要があります

​
Webhookのテスト

  1. テスト通知を送信 OneSignalダッシュボードから
  2. Webhookエンドポイントを監視 受信リクエストを確認
  3. ペイロード構造を検証 期待と一致するかを確認
  4. さまざまなシナリオをテスト：
    • 通知の表示
    • 通知本文のクリック
    • アクションボタンのクリック（設定されている場合）
    • 通知の却下（Chromeのみ）

​
次のステップ

Webhookをセットアップした後、次のことを検討してください：
  • 分析統合： Webhookデータを分析プラットフォームに転送
  • ユーザーセグメンテーション： Webhookイベントを使用してエンゲージメントに基づくユーザーセグメントを作成
  • 自動化されたワークフロー： プッシュ通知のインタラクションに基づいてメールキャンペーンまたはアプリ通知をトリガー
  • A/Bテスト： Webhookデータを使用してさまざまな通知戦略の効果を測定