イベントWebhook
イベント Webhook
Event Webhooks は、サブスクライバーのイベントが発生するとリアルタイムの HTTP コールバックを送信します。各ドメインごとに 1 つ以上のエンドポイントを設定して、構造化されたイベントデータを発生時に受け取れます。
設定
移動先 ドメイン設定 → Event Webhooks webhook エンドポイントを作成、編集、またはアーカイブします。
各 webhook は次を指定します:
URL: 宛先エンドポイント
ヘッダー: カスタムヘッダー。シークレット用の Liquid マクロを任意で使用できます
イベント: 購読する 1 つ以上のイベントタイプ
すべての配信は POST で、完全なイベントペイロードを含む JSON 本文です。
サポートされるイベント
通知
notification.displayed
サブスクライバーのデバイスに通知が表示される
通知
notification.clicked
サブスクライバーが通知をクリックする
プッシュ購読
push_subscription.created
デバイスがプッシュで到達可能になる
プッシュ購読
push_subscription.deleted
デバイスがプッシュで到達不可能になる
通知イベントはアクションごとに発火します。 各イベントは、1 アクションにつきサブスクライバーごとに 1 回発火します。10,000 人のサブスクライバーに送信された通知は、最大 10,000 件の個別イベントを生成します。
プッシュ購読イベントは変更時に発火します。 すでに購読解除されているデバイスに別の購読解除が行われても、何も変化しないためイベントは発生しません。
購読はデバイスごとです
プッシュ購読は人ではなく 1 台のデバイスです。スマートフォンとノートパソコンの両方で到達可能な人は 2 つの購読を持ち、2 件のイベントを生成します。
プッシュ購読イベントは有効化した時点で開始します
これらのイベントを購読しても、過去の履歴が再送されたり、オーディエンスの現在の状態が送信されたりはしません。購読が保存された瞬間からの変更のみを受け取るため、これらのイベントだけで構築した到達可能性は、その時点以降に変更されたデバイスに対してのみ完全です。オーディエンスの初期状態が必要な場合は、別途用意してください。
ペイロード構造
イベント固有のデータを含む固定エンベロープです。null フィールドは省略されます。
作成イベントには subscribed_url も含まれず reason_code.
削除イベントには reason_code も含まれず subscribed_url.
エンベロープ
version
int
ペイロードスキーマのバージョン
event_type
string
ドット区切りの名前空間付きイベント識別子（例: notification.clicked)
event_id
string（UUID）
このイベントの安定識別子です。重複排除キーとして使用します。
event_timestamp
string（ISO 8601、UTC）
イベントが発生した時刻
domain
object
このイベントが属する Pushly ドメイン
user
object
このイベントを発生させたサブスクライバー
data
object
イベント固有の内容。イベントの subject に一致するキーが 1 つだけ含まれます。
その data オブジェクトにはイベントの subject に一致する単一のキーが含まれます。例えば、 notification.* イベントでは、そのキーは notification; 一方 push_subscription.* イベントでは、 push_subscription.
その user と device ブロックは、すべてのイベントタイプで形も値も同一なので、どのイベントに含まれていたかに関係なく、それらをキーにできます。 device.user_agent は通知イベントにのみ含まれます。
すべてのタイムスタンプは、ミリ秒精度の ISO 8601 UTC 形式です。
プッシュ購読データ
subscribed_url
string
created
デバイスが購読したページ。判明している場合
reason_code
string
deleted
デバイスが到達不可能になった理由。下の表を参照してください。
理由コード
削除には必ず reason_codeが含まれます。対処すべき区別は、その人が意思決定をしたのか、それとも配信が単に動かなくなったのかです。最初の 2 つは本人の選択、次の 2 つはそうではありません。
user_unsubscribed
本人がオプトアウトしました。あなたのアプリやサイト内の操作で、またはブラウザーもしくは OS から通知許可を取り消したことによります。
data_deletion_request
ユーザーデータ削除リクエストの一環としてデバイスが削除されました。
token_invalidated
プッシュプロバイダーがデバイストークンを無効と判断して拒否しました。本人による操作はなく、同じデバイスから再度購読することもできます。
scrub
一定期間エンゲージメントがなかったため、リストの整理によってデバイスが削除されました。本人による操作はなく、トークンはまだ有効な可能性があります。
consolidated
デバイスのレコードが同一人物の別レコードに統合されました。 なお到達可能です、存続しているレコードの下で。下の注記を参照してください。
other
上記のいずれにも該当しない内部理由です。
consolidated その人が通知の受信をやめたことを意味するわけではありません。 ほかの理由コードはすべてそうです。これは、Pushly が 2 つのレコードを同一人物として認識し、それらを統合したことを意味します。本人は存続しているレコードの下で引き続き到達可能であり、そのレコードには別の user.idが付与されます。オプトアウトではなく識別子の変更として扱ってください。これで抑止すると、まだ購読中の人を削除してしまいます。
user_unsubscribed 自社インターフェースでのオプトアウトと、ブラウザーまたは OS レベルで取り消された権限の両方を含みます。この 2 つは互いに区別できません。
1 つの push_subscription.created イベントには含まれません reason_code。初回購読とデバイスが再び到達可能になった場合は、どちらも作成として報告され、区別されません。
見覚えのないものは、 reason_code 次と同じように扱ってください other — 参照: バージョニング.
ヘッダーマクロ
カスタムヘッダー値では、保存されたドメインシークレットを参照するための Liquid テンプレート構文をサポートしています:
ヘッダーテンプレートで明示的に参照されたシークレットのみが読み込まれます。システム管理のシークレット（先頭が _）のエイリアス）はテンプレートからアクセスできません。
ヘッダー
すべての配信には次が含まれます:
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>
検証アルゴリズム:
署名シークレットを UTF-8 バイト列としてエンコードします
シークレットをキーとして、元のリクエスト本文に対して HMAC-SHA256 を計算します
ダイジェストを16進エンコードします
の後ろの値と比較します
sha256=ヘッダー内の値を一定時間比較で
重要: 解析して再シリアル化したものではなく、元のリクエスト本文に対して検証してください。JSON のキー順序と空白はダイジェストに影響します。
リプレイ防止（任意）: 比較する X-Pushly-Delivery-Timestamp をサーバーの現在時刻と比較します。許容範囲（例: 5 分）より古い配信は拒否してください。
署名シークレットは次で確認できます ドメイン設定 → Event Webhooks → Signing Secret.
冪等性
Pushly は 1 アクションにつきサブスクライバーごとに 1 件のイベントを生成します。エンドポイントが失敗またはタイムアウトした場合、イベントは複数回配信されることがあります。そのため、 event_id 重複排除に使用し、確認応答後に非同期で処理する場合は、そちら側で永続キューを使ってください。
1 つの event_id は特定の変更を識別し、その再配信の間も同じ値のままです。
配信
タイムアウト
エンドポイントは 5 秒以内に応答しなければなりません。処理にそれ以上かかる場合は、すぐに応答して非同期で処理してください。
再試行
1
即時
2
1 回目の失敗の 4 秒後
3
2 回目の失敗の 16 秒後
3 回の試行後、イベントはデッドレターキューに移動します。
再試行される: HTTP 5xx、タイムアウト、接続エラー。再試行されない: HTTP 4xx、SSRF ブロック。
順序
イベントは順不同で到着する場合があります。 event_timestamp を時系列順に並べるためであり、配信順ではありません。
これは、同じデバイスの購読と購読解除が一連の流れを表すプッシュ購読イベントで特に重要です。 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 非推奨期間を伴って。
最終更新