イベントWebhook

イベント Webhook

Event Webhooks は、購読者イベントが発生したときにリアルタイムの HTTP コールバックを配信します。ドメインごとに 1 つ以上のエンドポイントを設定して、構造化されたイベントデータを発生時に受信できます。

設定

次へ移動 ドメイン設定 → Event Webhooks を開いて、Webhook エンドポイントの作成、編集、アーカイブを行います。

各 Webhook には次が指定されます:

• URL: 宛先エンドポイント

• ヘッダー: カスタムヘッダー。秘密情報には任意で Liquid マクロを使用できます

• イベント: 購読する 1 つ以上のイベント प्रकार

すべての配信は POST で、完全なイベントペイロードを含む JSON 本文を伴います。

サポートされているイベント

グループ	イベント	説明
通知	notification.displayed	購読者のデバイスに通知が表示される
通知	notification.clicked	購読者が通知をクリックする

各イベントは、購読者 1 人あたり 1 アクションにつき 1 回発生します。10,000 人の購読者に送信された通知では、最大 10,000 件の個別イベントが生成されます。

ペイロード構造

イベント固有のデータを持つ固定エンベロープ。Null フィールドは省略されます。

通知イベント

{
  "version": 1,
  "event_type": "notification.displayed",
  "event_id": "d426d74a-b0cc-46e3-9a6d-d12ac346effe",
  "event_timestamp": "2026-05-08T14:17:30.452Z",
  "domain": {
    "id": 1234,
    "name": "Cafe 80s",
    "url": "cafe80s.com"
  },
  "user": {
    "id": "atk3i6E0NtohVy4UlvvkGQfl6J5wNTYp",
    "external_id": "11298b50-c1a7-4db3-aebc-829fed8b0d94",
    "device": {
      "platform": "web",
      "type": "desktop",
      "os": "macos",
      "os_version": "14.4",
      "browser": "chrome",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
      "time_zone": "America/Chicago",
      "location": {
        "city": "Hill Valley",
        "province": "California",
        "country_code": "US",
        "postal_code": "19851",
        "continent_code": "NA"
      }
    }
  },
  "data": {
    "notification": {
      "id": 21015,
      "title": "時計塔を救え!",
      "body": "ウィルソン市長の保存協会があなたの助けを必要としています — 雷が落ちる前に寄付を",
      "keywords": ["hill-valley", "preservation", "clock-tower"],
      "send_timestamp": "2026-05-08T14:17:25.000Z",
      "source": "manual",
      "delivery_type": "scheduled",
      "segment_ids": [1955, 1985],
      "segment_names": ["Hill Valley Residents", "Preservation Society Members"],
      "campaign": {
        "id": 88,
        "step_id": 1
      }
    }
  }
}

エンベロープ

フィールド	型	説明
version	int	ペイロードスキーマのバージョン
event_type	string	ドット名前空間のイベント識別子（例: notification.clicked)
event_id	string (UUID)	このイベントの स्थिर 識別子。重複排除キーとして使用します。
event_timestamp	string (ISO 8601, UTC)	イベントが発生した時刻
domain	object	イベントが属する Pushly ドメイン
user	object	イベントをトリガーした購読者
data	object	イベント固有のコンテンツ。イベントの विषयに一致するキーをちょうど 1 つ含みます。

The data object には、イベントの subject に一致する単一のキーが含まれます。For notification.* events, that key is notification.

すべてのタイムスタンプは、ミリ秒精度の ISO 8601 UTC です。

ヘッダーマクロ

カスタムヘッダー値では、保存されたドメインの秘密情報を参照するために Liquid テンプレート構文を使用できます:

Authorization: Bearer {{ secret.analytics_token }}

ヘッダーテンプレートで明示的に参照された秘密情報のみが読み込まれます。システム管理の秘密情報（エイリアスが次で始まるもの _) はテンプレートからアクセスできません。

ヘッダー

各配信には次が含まれます:

ヘッダー	説明
X-Pushly-Webhook-Id	この配信を生成した Webhook 設定を識別する UUID
X-Pushly-Event-Id	ペイロード内の一意のイベント ID。重複排除に使用します。
X-Pushly-Signature	リクエスト本文の HMAC-SHA256 署名（下記参照）
X-Pushly-Delivery-Timestamp	配信が開始された時点の Unix タイムスタンプ（秒）
X-Pushly-Attempt-Number	1 から始まる試行番号
Content-Type	application/json

予約済みのヘッダー名（Content-Type, Host, Content-Length, Transfer-Encoding、および X-Pushly-で始まるもの）は、Webhook 設定のカスタムヘッダーで上書きできません。

署名の検証

すべての配信には、真正性を検証するための X-Pushly-Signature ヘッダーが含まれます。

形式: sha256=<hex_digest>

検証アルゴリズム:

1. 署名秘密鍵を UTF-8 バイト列としてエンコードする

2. 秘密鍵をキーとして、元のリクエスト本文に対して HMAC-SHA256 を計算する

3. ダイジェストを 16 進数でエンコードする

4. ヘッダー内の sha256= の後の値と、一定時間比較で照合する

重要: 解析して再シリアライズしたものではなく、元のリクエスト本文に対して検証してください。JSON のキー順序と空白はダイジェストに影響します。

リプレイ防止（任意）: を X-Pushly-Delivery-Timestamp サーバーの現在時刻と比較します。許容ウィンドウ（例: 5 分）より古い配信は拒否してください。

署名秘密鍵は次で確認できます ドメイン設定 → Event Webhooks → 署名秘密鍵.

冪等性

Pushly は、購読者 1 人あたり 1 アクションにつき 1 件のイベントを生成します。エンドポイントが失敗したりタイムアウトしたりした場合、イベントは複数回配信されることがあります — 重複排除には event_id を使用し、承認後に非同期で処理する場合は、耐久性のあるキューを自前で使用してください。

配信

タイムアウト

エンドポイントは 5 秒以内に応答する必要があります。処理にそれ以上かかる場合は、すぐに応答を返して非同期で処理してください。

再試行

試行	遅延
1	即時
2	最初の失敗から 4 秒後
3	2 回目の失敗から 16 秒後

3 回試行した後、イベントは dead-letter queue に移動します。

再試行あり: HTTP 5xx、タイムアウト、接続エラー。再試行なし: HTTP 4xx、SSRF ブロック。

順序

イベントは順不同で到着する場合があります。配信順ではなく、 event_timestamp を時系列順の並び替えに使用してください。

ネットワークセキュリティ

Webhook 配信の主な認証メカニズムは HMAC 署名検証（上記）です。すべての配信には X-Pushly-Signature ヘッダーが含まれ、署名秘密鍵を使ってリクエスト本文と照合できます。これは、リクエストが Pushly から送られたことを示す暗号学的証明であり、ネットワークの発信元に依存せず、当社側のインフラ変更にも耐性があります。

IP 許可リスト

固定の送信元 IP の一覧は公開していません。セキュリティまたはコンプライアンス方針で IP ベースのネットワーク制御が必要な場合は、Pushly のアカウントマネージャーに連絡して要件をご相談ください。

TLS

Webhook エンドポイントは HTTPS で到達可能である必要があります。Pushly はプレーン HTTP の URL には配信しません。TLS 1.2 以上を必須とし、標準の公開認証局に対してエンドポイントの証明書を検証します。自己署名証明書はサポートされていません。

SSRF 保護

Pushly は接続前に、すべての宛先 URL をプライベートおよび予約済み IP 範囲と照合して検証します。プライベート（RFC 1918）、ループバック、リンクローカル、インスタンスメタデータの各アドレスへのリクエストは拒否されます。

バージョニング

新しいフィールドとイベントタイプは、 versionを増やさずに追加されます。ハンドラーでは未知のフィールドを無視してください。

破壊的変更（フィールドの削除または名前変更）がある場合は、 version が増え、非推奨期間が設けられます。