Webhook 統合ガイド

Webhook を使えば、外部アプリケーションが Postion サイトで発生したイベントのリアルタイム通知を受け取れます。ワークフローの自動化、CRM とのデータ同期、メールのトリガーなど、さまざまな用途に活用できます。

Webhook とは？

Webhook は HTTP コールバックです。Postion で特定のイベント（新規購読者や購入など）が発生すると、あなたが指定した URL にそのイベントのデータを含む POST リクエストが送信されます。

Webhook のセットアップ

ステップ 1：Webhook エンドポイントを作成

1. ダッシュボード → Webhook に移動
2. 「Webhook を追加」 をクリック
3. エンドポイント URL を入力（例：https://your-app.com/api/postion-webhook）
4. 受信したいイベントを選択

ステップ 2：イベントを選択

ステップ 3：エンドポイントを認証

Webhook 作成後、Postion があなたの URL に認証リクエストを送信します。エンドポイントは 200 OK ステータスで応答して、準備完了を確認する必要があります。

Webhook ペイロードの形式

すべての Webhook ペイロードは以下の構造に従います：

{
  "event": "subscriber.created",
  "timestamp": "2025-07-15T10:30:00Z",
  "data": {
    "id": "sub_abc123",
    "email": "[email protected]",
    "name": "Jane Doe",
    "plan": "pro",
    "site_id": "site_xyz789"
  }
}

セキュリティ：Webhook 署名の検証

すべての Webhook リクエストには署名ヘッダー（X-Postion-Signature）が含まれます。リクエストが本当に Postion からのものであることを確認するために、この署名を検証してください。

import crypto from 'crypto';
 
function verifyWebhookSignature(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return hash === signature;
}

一般的な連携パターン

CRM との同期

購読者が登録したら、CRM に自動的にコンタクトを作成：

1. subscriber.created イベントをリッスン
2. 購読者のメールと名前を抽出
3. CRM（HubSpot、Salesforce など）でコンタクトを作成/更新

カスタムサービスでウェルカムメールを送信

自分のメールサービスを通じてパーソナライズされたウェルカムメールをトリガー：

1. subscriber.created イベントをリッスン
2. 購読者データを使ってメールをパーソナライズ
3. 好みのメールプロバイダ（SendGrid、Mailgun など）で送信

Slack 通知

重要なイベントが発生したときに Slack で通知を受け取る：

1. Slack の Incoming Webhook URL を作成
2. Postion の Webhook を受け取るミドルウェアを設定
3. フォーマットしたメッセージを Slack チャネルに転送

アナリティクストラッキング

アナリティクスプラットフォームにイベントを記録：

1. すべての関連イベントをリッスン
2. Mixpanel、Amplitude、またはカスタムアナリティクスに転送
3. 購読者ライフサイクルを追跡するダッシュボードを構築

リトライポリシー

エンドポイントが利用不可の場合、Postion は指数バックオフでリトライします：

5 回失敗後、Webhook は失敗マークが付けられ、メール通知が届きます。

トラブルシューティング

「Webhook がイベントを受信しない」

• エンドポイント URL がパブリックにアクセス可能か確認（localhost ではないこと）
• エンドポイントが 10 秒以内に 200 ステータスコードを返しているか確認
• Webhook 設定で正しいイベントが選択されているか確認

「無効な署名」

• ダッシュボードの正しい Webhook シークレットを使用しているか確認
• パースした JSON ではなく、生のリクエストボディに対して HMAC を計算しているか確認

「イベントの順序が乱れる」

ネットワーク状況により、Webhook が順不同で到着する場合があります。timestamp フィールドを使って正しいイベント順序を判断してください。

API の完全なリファレンスは Public API ドキュメント をご覧ください。 Webhook システムのアーキテクチャの技術詳細は Webhook アーキテクチャ をご覧ください。