Webhook は、新しいメンバーの参加や支払いの受領など、コミュニティで何かが起きるたびに、Mateflow からあなたが管理する URL に HTTPS リクエストを送ります。Webhook を使うと、CRM、メールツール、独自のアプリを同期させておけます。Webhook は管理画面 → 設定 → 連携 → Webhook で設定します。
対象者:オーナーと管理者。 · 場所:ウェブ(管理画面)。 · プラン:Webhook を使えるかどうかと、作成できる数は、プラットフォームプランによって異なります。プランに含まれなくなると、配信は停止します。Webhook は保持され、アップグレードすると再開します。
Webhook のエンドポイントを作成する
- 管理画面 → 設定 → 連携に移動し、Webhook タブを開きます。
- Webhook を追加をクリックします。
- 名前とHTTPSのエンドポイント URLを入力します。
- 必要に応じて署名シークレットを生成し、受信側にコピーします。検証方法は後述します。
- 受信するイベントを1つ以上明示的に選びます。検索やカテゴリ選択ができ、イベントの説明から対応する開発者向け資料を開けます。
- Webhook を作成をクリックします。新規Webhookは無効状態で保存されます。
- 保存後にサンプルを送信し、受信側の準備ができてから有効にします。
Webhook を追加ボタンにアップグレードの案内が表示される場合は、プランに Webhook が含まれていないか、プランの Webhook 数の上限に達しています。プランの使用量と上限を確認するを参照してください。
購読できる Webhook イベント
| カテゴリー | イベント |
|---|---|
| メンバー | メンバー参加、メンバー退会、ロール変更、メンバー停止(BANでも送信されます)、メンバー復帰、アクセスグループへのメンバー追加、アクセスグループからのメンバー削除 |
| コンテンツ | 投稿作成、コメント作成、投稿削除、コメント削除 |
| 支払い | 支払い受領、支払い失敗、サブスクリプション作成、サブスクリプション更新、サブスクリプションキャンセル、返金実行 |
古い Webhook には、現在は利用できないイベントが表示されることがあります。これらは削除できますが、再び追加することはできません。
旧設定のイベント一覧が空の場合は、イベントなしではなく全イベントを意味します。そのまま維持するか、購読を明示的に選び直します。ほかの設定を変えるだけなら未対応イベントは保持されます。購読を変更する場合は未対応項目を外し、現在のイベントを1つ以上選びます。一覧を読み込めないときは、選択やテストの前に再試行します。
アクセスグループの Webhook イベントの仕組み
アクセスグループへのメンバー追加とアクセスグループからのメンバー削除(アクセスグループの旧称:メンバーティア)は、メンバーのグループが実際に変わったときに発生します。各イベントは 1 人のメンバーと 1 つのグループを対象とし、メンバーのユーザー名とメールアドレス、グループ名、変更の原因(管理者、サブスクリプション、招待、デフォルトのアクセスグループ、グループの削除)を含みます。
- メンバー参加より前にアクセスグループのイベントは送信されません。そのため、新しいメンバーがサインアップ時に入るデフォルトのグループは通知されず、メンバーが承認を待っている間の変更も通知されません。
- アクセスグループを削除すると、そのグループに所属していたメンバーごとに削除イベントが 1 件ずつ送信されます。これらのイベントと、デフォルトのグループの設定によるイベントは、数分遅れて届くことがあります。
- サブスクリプションが付与するグループを削除すると、削除イベントの後に追加イベントが送信されます。サブスクリプションがすぐにグループを付与し直すためです。メンバーのアクセスグループを追加・削除するを参照してください。
メンバー退会の Webhook イベントの仕組み
メンバー退会は、誰かがコミュニティのメンバーでなくなったときに 1 回送信されます。CRM やメーリングリストからその人を削除するのに使えます。送信されるのは次の場合です。
- 管理者がコミュニティから削除またはメンバーを匿名化を使ったとき
- メンバーが自分のアカウントを削除したとき。予約された削除は、申請した時点ではなく 30 日間の猶予期間が終わった時点で対象になります。削除が取り消された場合は何も送信されません
- データ保持ポリシーによって非アクティブなメンバーが消去されたとき。毎晩実行されるため、多くのイベントが一度に届くことがあります
各イベントには、退会前のメンバーのユーザー名とメールアドレスが含まれます。アカウントが匿名化された場合も同じなので、自分のシステムでその人を見つけられます。どのように退会したかも含まれ、管理者が削除または匿名化した場合はどの管理者かもわかります。管理者がメンバーを削除するときに内部メモ(任意) に記入した場合は、そのメモも含まれます。
メンバーが自分のアカウントを無効化したとき、停止またはBANされたとき(この場合はメンバー停止が送信されます)、スペースから退出したとき、参加を完了していないときは、メンバー退会は送信されません。退会したメンバーが持っていたアクセスグループについて、アクセスグループからのメンバー削除は送信されません。
カードにすべてのイベントを送信中と表示されている接続済みアプリも、メンバー退会の送信を始めます。Slack や Discord のチャンネルにも届きます。不要な場合は、設定を編集を選んで送信するイベントを選択してください。連携の概要:API、Webhook、Zapierを参照してください。
署名シークレットで 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=より後の部分と比較します。一致しない場合は、リクエストを拒否します。 - 必要に応じて、タイムスタンプが数分以上前のリクエストを拒否し、リプレイ攻撃を防ぎます。
自動化ルールの Webhook を送信アクションから送られるリクエストも、ルールにシークレットがある場合は同じ方法で署名されます。ルールでタスクを自動化するを参照してください。
保存すると、シークレットは非表示になります。シークレットを維持するには、Webhook を編集するときにこの欄を空欄のままにします。シークレットをローテーションするには、新しいシークレットを生成し、同時にサーバーも更新します。
Webhook をテスト・一時停止・編集・削除する
テストや配信ログを開く前に保存します。操作メニューでテスト画面を開き、サンプル送信に対応する購読済みイベントを選んでテスト送信をクリックします。test=trueのサンプルは保存済みURLに送られ、無効状態でもテストできます。受信側ではテストデータを識別してください。2xxはHTTP受信の確認であり、独自の業務処理の完了ではありません。ステータス、応答、ログを確認します。
テスト後に有効化し、実際の配信を止めるには無効化します。有効なWebhookの編集は保存時に即時反映されます。削除するとWebhookと配信ログが完全に消えます。設定変更後は以前の結果が無効になるため、保存済み設定で再テストします。
Webhook の配信と再試行を確認する
配信ログタブを開くと、各リクエストとその HTTP ステータス、所要時間、送信元が表示されます。1 つの Webhook の配信を見るには、Webhook で絞り込むを使います。詳細を表示をクリックすると、リクエストペイロードとレスポンスボディの全体を確認できます。配信ログは 30 日間保持されます。
配信に失敗すると、Mateflow は 1 分後、10 分後、1 時間後、6 時間後に自動的に再試行します。HTTP 429 と 408 のレスポンスも再試行されますが、それ以外の 4xx は再試行されません。再試行が尽きたとき、または再試行されない 4xx のときは、オーナーと管理者にメールが届きます(Webhook ごとに 1 日 1 回まで)。
自分で配信をもう一度送信するには、その行の再送信をクリックします。同じ本文が再度署名され、Webhook の現在の URL に送信されます。更新すると、結果が新しい行として表示されます。削除またはオフにした Webhook からは再送信できません。試行ごとに行が追加されます。自動再試行には新しい配信 ID が付き、再送信 では元の ID のままです。イベント ID は変わりません。イベント ID が同じ行は、1 つのイベントに対する試行です。配信は重複したり、順序が入れ替わったりすることがあるため、サーバー側でイベント ID をもとに重複を排除してください。ペイロードのフィールドとコード例については、Webhook タブの Webhook 開発者向けリファレンス カードでドキュメントを開くをクリックするか、mateflow.com/developers/webhooks を参照してください。このリンクは開発者にそのまま送れます。
配信ログはイベント、結果、Webhook、日付、送信元、プラットフォームで絞り込めます。統計は選んだ範囲と期間を対象とし、テスト、自動再試行、手動再送を含むHTTP試行回数を数えます。重複のない業務イベント数ではありません。利用可能な履歴と保持期間も表示されます。設定の合計は別の時点情報で、有効、無効、最近失敗のある有効Webhookを区別します。
関連記事
このガイドは役に立ちましたか?