> For the complete documentation index, see [llms.txt](https://documentation.pushly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.pushly.com/pushly-ja/platform/ibentowebhook.md).

# イベントWebhook

## イベント Webhook

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

### 設定

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

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

* **URL**: 宛先エンドポイント
* **ヘッダー**: カスタムヘッダー。秘密情報には任意で Liquid マクロを使用できます
* **イベント**: 購読する 1 つ以上のイベント प्रकार

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

<figure><img src="/files/d616c9d025c229be835224257357518d0e568c11" alt=""><figcaption></figcaption></figure>

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

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

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

### ペイロード構造

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

{% tabs %}
{% tab title="通知イベント" %}
{% code expandable="true" %}

```javascript
{
  "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
      }
    }
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### エンベロープ

| フィールド             | 型                      | 説明                                           |
| ----------------- | ---------------------- | -------------------------------------------- |
| `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` が増え、非推奨期間が設けられます。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.pushly.com/pushly-ja/platform/ibentowebhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.