コミュニティ Webhook

1. コミュニティの管理画面で 設定 → インテグレーション → Webhook を開き、Webhook を作成します。URL を入力し、イベントを選び、シークレットを生成して、有効にしてください。
2. 各リクエストは次の順序で処理します。
   1. 生のリクエスト本文を読み取り、署名を検証する。
   2. test が true なら、200 を返して処理を終える。
   3. event_id で重複排除する。
   4. 処理は自前のキューに積み、10 秒以内に 2xx を返す。
3. Webhook をテストをクリックしてテストリクエストを送信し、配信ログを開いてリクエストとレスポンスを確認します。

• Webhook のないプランにダウングレードしても Webhook の設定は保持されますが、配信もログ記録も行われません。アップグレードすると配信が再開されます。
• Webhook は管理コンソールで作成・管理します。Community Open API には Webhook 用のエンドポイントはありません。

設定

ヘッダー

カスタム Webhook には X-Mateflow-Delivery-Id ヘッダーはありません。delivery_id は本文から読み取ってください。

本文

{
  "event": "payment.received",
  "event_id": "86116692152877061",
  "occurred_at": "2026-11-03T00:00:00Z",
  "delivery_id": "86116692152877060",
  "timestamp": "2026-11-03T00:00:01Z",
  "webhook_id": "qP3aXm71Bd",
  "site_id": "Z5Kf08mFv8r",
  "data": {
    "member_id": "b7Lq2WxR9e",
    "username": "sample_member",
    "email": "sample.member@example.com",
    "invoice_id": "in_1Abc",
    "subscription_id": "sub_1Abc",
    "amount_cents": 2900,
    "currency": "usd",
    "period_start": "2026-11-03T00:00:00Z",
    "period_end": "2026-12-03T00:00:00Z"
  }
}

X-Mateflow-Signature = "sha256=" + hex(
  HMAC-SHA256(secret, X-Mateflow-Timestamp + "." + raw_request_body)
)

• 生のバイト列を使ってください。本文では HTML で特殊な文字がエスケープされることがあるため、JSON をパースして再びシリアライズするとバイト列が変わり、署名が一致しません。
• タイムスタンプは本文ではなくヘッダーから取ってください。手動再送で更新されるのは、ヘッダーのタイムスタンプと署名だけです。
• タイムスタンプの検査はリトライの妨げになりません。自動リトライも手動再送も、そのつど署名し直されるため、5 分のウィンドウで十分です。

const crypto = require('crypto');

// rawBody must be the untouched bytes, e.g. from express.raw({ type: 'application/json' }).
function verifyMateflowSignature(rawBody, headers, secret, toleranceSeconds = 300) {
  const timestamp = headers['x-mateflow-timestamp'];
  const received = headers['x-mateflow-signature'] || '';
  if (!timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
    return false;
  }
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest('hex');
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hashlib
import hmac
import time


def verify_mateflow_signature(raw_body: bytes, headers, secret: str, tolerance_seconds: int = 300) -> bool:
    timestamp = headers.get("X-Mateflow-Timestamp", "")
    received = headers.get("X-Mateflow-Signature", "")
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > tolerance_seconds:
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(received.encode(), expected.encode())

テストベクター

署名の計算が正しいかどうかの確認に、これらの値を使ってください。タイムスタンプは期限切れなので、テスト中は時間ウィンドウを緩めてください。

secret                 my_signing_secret
X-Mateflow-Timestamp   1793664000
raw body (UTF-8)       {"event":"member.joined","data":{"username":"张三"}}
X-Mateflow-Signature   sha256=3f4c83828ce0086150c9bd48c1654899357b7c05265c1d1b6c172225ee04b4b4

シークレットのローテーション

新しいシークレットは保存した時点で有効になり、キューに入っているリトライもそれで署名されます。Mateflow が両方で署名する期間はないため、切り替え中は受信側で古いシークレットと新しいシークレットの両方を受け付けるようにしてください。

• リトライのスケジュール:失敗後、Mateflow は 1 分、10 分、1 時間、6 時間の順に待ちます。最初の試行を含めると、約 7 時間で最大 5 回の試行になります。
• 配信を断念するとき:リトライを使い切った場合、またはリトライ対象外のステータスだった場合、コミュニティのオーナーと管理者にメールが届きます。Webhook ごとに 24 時間あたり最大 1 通です。
• 途中で止まる場合:Webhook が削除または無効にされた場合、あるいはプランに Webhook が含まれなくなった場合、以降の試行は送信もログ記録もされません。
• リダイレクト:配信はリダイレクトに従いますが、301、302、303 では POST が本文のない GET に変わります。最終的な URL を入力してください。http から https へのリダイレクトには頼らないでください。

手動再送

配信ログの再送信は、配信を Webhook の現在の URL にもう一度送ります。

• 本文は、event_id、delivery_id、timestamp を含めて同一です。タイムスタンプヘッダーと署名は新しくなります。
• 試行は 1 回のみで、失敗してもリトライされません。結果はログに新しい行として表示されます。
• 再送できるのはカスタム Webhook の配信のみで、その Webhook が存在し、有効になっている必要があります。

配信ログ

ログは 30 日間保持されます。各レスポンス本文は、先頭の 4 KB のみが保存されます。

• At-least-once です。同じイベントが複数回届くことがあります。event_id で重複排除してください。
• 金銭が絡む処理には、2 つ目のチェックを加えてください。Mateflow は同一の支払いや、同一のサブスクリプションの開始・終了を既に重複排除していますが、そのチェックが利用できないときは、破棄せずに送信します。その場合、2 つのイベントは異なる event_id を持ちます。invoice_id、subscription_id、order_id もあわせて確認してください。
• 順序は保証されません。配信は並列に実行されリトライもされるため、メンバーの access_group_removed と access_group_added が逆の順序で届くことがあります。どちらが先だったかを判断するには、秒単位で正確な occurred_at を使ってください。
• まれに欠落することがあります。イベントはデータがコミットされた後にキューへ積まれるため、その 2 つのステップの間でプロセスが終了すると、イベントが失われます。
• 状態を同期するなら照合してください。イベントは何かが変わったことを知らせる合図として扱い、現在の状態は Open API（たとえば members.read スコープでの /member/get）から読み取り、定期的に全件の比較を行ってください。Open API はメールアドレスを返さないため、メールアドレスはイベントから取得してください。

全フィールド共通のルール

• Mateflow の ID は hashid 文字列で、API が使うものと同じ値です。値が 0 の場合はエンコードされず、数値の 0 として現れます。
• member_id と user_id は同じ人物を指します。member.joined、投稿イベント、コメントイベントは user_id を使い、それ以外はすべて member_id を使います。
• Stripe の ID はそのまま渡されます。invoice_id、subscription_id、charge_id、payment_intent_id が該当します。
• 時刻は UTC の RFC 3339 です。
• 金額は、その通貨の最小単位の整数です（USD ならセント）。currency は小文字の通貨コードです。
• 該当しない任意フィールドは省略されます。null や空文字列にはなりません。
• フィールドと列挙値は追加されるだけで、変更されることはありません。受信側は、新しいものが増えても動作するようにしてください。

全イベント