Webhook は、新しいメンバーの参加や支払いの受領など、コミュニティで何かが起きるたびに、Mateflow からあなたが管理する URL に HTTPS リクエストを送ります。Webhook を使うと、CRM、メールツール、独自のアプリを同期させておけます。Webhook は管理画面 → 設定 → 連携 → Webhook で設定します。
対象者：オーナーと管理者。 · 場所：ウェブ（管理画面）。 · プラン：Webhook を使えるかどうかと、作成できる数は、プラットフォームプランによって異なります。
Webhook のエンドポイントを作成する
- 管理画面 → 設定 → 連携に移動し、Webhook タブを開きます。
- Webhook を追加をクリックします。
- 名前（100 文字未満）とエンドポイント URL を入力します。URL は HTTPS である必要があります。
- 任意ですが、推奨します。シークレット（任意） で生成ボタン（シークレットを生成）をクリックし、シークレットをコピーしてサーバーで使います。下の署名のセクションを参照してください。
- イベントで、送信するイベントにチェックを入れます。カテゴリー名にチェックを入れると、そのカテゴリーのイベントをすべて選べます。
- Webhook がイベントの受信を始めるように、有効はオンのままにします。
- Webhook を作成をクリックします。
Webhook を追加ボタンにアップグレードの案内が表示される場合は、プランに Webhook が含まれていないか、プランの Webhook 数の上限に達しています。プランの使用量と上限を確認するを参照してください。
購読できる Webhook イベント
| カテゴリー | イベント |
|---|---|
| メンバー | メンバー参加、ロール変更、メンバー停止（BAN でも送信されます）、メンバー復帰、アクセスグループへのメンバー追加、アクセスグループからのメンバー削除 |
| コンテンツ | 投稿作成、コメント作成、投稿削除、コメント削除 |
| 支払い | 支払い受領、支払い失敗、サブスクリプション作成、サブスクリプション更新、サブスクリプションキャンセル、返金実行 |
古い Webhook には、現在は利用できないイベントが表示されることがあります。これらは削除できますが、再び追加することはできません。
アクセスグループの Webhook イベントの仕組み
アクセスグループへのメンバー追加とアクセスグループからのメンバー削除（アクセスグループの旧称：メンバーティア）は、メンバーのグループが実際に変わったときに発生します。各イベントは 1 人のメンバーと 1 つのグループを対象とし、メンバーのユーザー名とメールアドレス、グループ名、変更の原因（管理者、サブスクリプション、招待、デフォルトのアクセスグループ、グループの削除）を含みます。
- メンバー参加より前にアクセスグループのイベントは送信されません。そのため、新しいメンバーがサインアップ時に入るデフォルトのグループは通知されず、メンバーが承認を待っている間の変更も通知されません。
- アクセスグループを削除すると、そのグループに所属していたメンバーごとに削除イベントが 1 件ずつ送信されます。これらのイベントと、デフォルトのグループの設定によるイベントは、数分遅れて届くことがあります。
- サブスクリプションが付与するグループを削除すると、削除イベントの後に追加イベントが送信されます。サブスクリプションがすぐにグループを付与し直すためです。メンバーのアクセスグループを追加・削除するを参照してください。
署名シークレットで Webhook の署名を検証する
Webhook にシークレットがある場合、Mateflow は各リクエストに HMAC-SHA256 で署名します。サーバーは、リクエストが Mateflow から送られ、改ざんされていないことを確認できます（署名の検証）。各リクエストには、次の 2 つのヘッダーが付きます。
X-Mateflow-Timestamp：リクエストが送信された時刻（Unix 秒）。X-Mateflow-Signature：sha256=に続けて、16 進エンコードされた署名。
サーバーでリクエストを検証するには：
- JSON を解析する前に、受け取ったままの生のリクエスト本文を読み取ります。
- 署名対象の文字列を作ります。
X-Mateflow-Timestampの値、ピリオド（.）、生の本文の順につなげます。 - シークレットを鍵として、その文字列の HMAC-SHA256 を計算し、16 進エンコードします。
- 定数時間の比較を使って、
X-Mateflow-Signatureのsha256=より後の部分と比較します。一致しない場合は、リクエストを拒否します。 - 必要に応じて、タイムスタンプが数分以上前のリクエストを拒否し、リプレイ攻撃を防ぎます。
移行期間中は、リクエストの X-Webhook-Secret ヘッダーにシークレットそのものも含まれます。このヘッダーに頼らず、署名を検証してください。
自動化ルールの Trigger webhook アクションから送られるリクエストは、仕組みが異なります。署名は付かず、ルールのシークレットが X-Webhook-Secret ヘッダーでそのまま送られます。ルールでタスクを自動化するを参照してください。
保存すると、シークレットは非表示になります。シークレットを維持するには、Webhook を編集するときにこの欄を空欄のままにします。シークレットをローテーションするには、新しいシークレットを生成し、同時にサーバーも更新します。
Webhook をテスト・一時停止・編集・削除する
Webhook の操作メニューでは、次のことができます。
- Webhook をテストは、エンドポイントにテストリクエストを送ります。
- 無効にするは、Webhook を削除せずに配信を止めます。有効にするで再びオンにします。
- 編集では、名前、URL、シークレット、イベントを変更します。
- 削除は、Webhook とそのすべての配信ログを削除します。この操作は元に戻せません。
一覧には、各 Webhook のステータス、最終実行、成功と失敗の件数が表示されます。最近の配信が失敗している Webhook には、エラーのステータスが表示されます。
Webhook の配信と再試行を確認する
配信ログタブを開くと、各リクエストとその HTTP ステータス、所要時間、送信元が表示されます。詳細を表示をクリックすると、リクエストペイロードとレスポンスボディの全体を確認できます。配信ログは 30 日間保持されます。
配信に失敗すると、Mateflow は最大 3 回まで自動的に再試行します。自分で配信を再送するボタンはありません。試行ごとに行が追加され、新しい配信 ID が付きますが、イベント ID は変わりません。イベント ID が同じ行は、1 つのイベントに対する試行です。配信は重複したり、順序が入れ替わったりすることがあるため、サーバー側でイベント ID をもとに重複を排除してください。ペイロードのフィールドについては、mateflow.com/developers の開発者向けドキュメントを参照してください。
関連記事
このガイドは役に立ちましたか？