커뮤니티 웹훅

1. 커뮤니티 관리자 페이지에서 설정 → 연동 → 웹훅을 열고 웹훅을 만드세요. URL을 입력하고, 이벤트를 고르고, 시크릿을 생성한 다음 켜면 됩니다.
2. 요청마다 다음 순서로 처리하세요.
   1. 원본 요청 본문을 읽고 서명을 검증합니다.
   2. test가 true이면 200을 반환하고 중단합니다.
   3. event_id로 중복을 제거합니다.
   4. 작업은 자체 큐에 넣고 10초 안에 2xx를 반환합니다.
3. 웹훅 테스트를 눌러 테스트 요청을 보낸 다음, 전송 로그를 열어 요청과 응답을 확인하세요.

• 웹훅이 없는 요금제로 다운그레이드해도 웹훅 설정은 유지되지만, 전송도 로그 기록도 이루어지지 않습니다. 다시 업그레이드하면 전송이 재개됩니다.
• 웹훅은 관리자 콘솔에서 만들고 관리합니다. Community Open API에는 웹훅용 엔드포인트가 없습니다.

구성

헤더

커스텀 웹훅에는 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번 시도합니다.
• 전송을 포기하는 경우: 재시도 횟수를 모두 소진했거나 재시도 대상이 아닌 상태 코드를 받으면, 커뮤니티 소유자와 관리자에게 이메일이 발송됩니다. 웹훅 하나당 24시간에 최대 한 통입니다.
• 도중에 중단되는 경우: 웹훅이 삭제되거나 꺼지거나, 요금제에 더 이상 웹훅이 포함되지 않으면 이후 시도는 전송도 기록도 되지 않습니다.
• 리다이렉트: 전송은 리다이렉트를 따라가지만, 301, 302, 303은 POST를 본문 없는 GET으로 바꿉니다. 최종 URL을 입력하고, http에서 https로의 리다이렉트에 의존하지 마세요.

수동 재전송

전송 로그에서 다시 보내기를 누르면 웹훅의 현재 URL로 전송을 다시 보냅니다.

• 본문은 event_id, delivery_id, timestamp를 포함해 동일합니다. 타임스탬프 헤더와 서명은 새로 만들어집니다.
• 한 번만 시도하며, 실패해도 재시도하지 않습니다. 결과는 로그에 새 행으로 나타납니다.
• 커스텀 웹훅 전송만 재전송할 수 있으며, 웹훅이 아직 존재하고 켜져 있어야 합니다.

전송 로그

로그는 30일 동안 보관됩니다. 응답 본문은 각각 처음 4KB만 저장됩니다.

• 최소 한 번 전송(at least once). 같은 이벤트가 두 번 이상 도착할 수 있습니다. event_id로 중복을 제거하세요.
• 돈과 관련된 처리에는 두 번째 확인을 추가하세요. Mateflow는 같은 결제와 같은 구독의 시작 또는 종료를 이미 중복 제거하지만, 그 확인을 사용할 수 없을 때는 버리지 않고 보내며, 이 경우 두 이벤트의 event_id 값은 서로 다릅니다. invoice_id, subscription_id, order_id도 함께 확인하세요.
• 순서는 보장되지 않습니다. 전송은 병렬로 실행되고 재시도되므로, 한 멤버의 access_group_removed와 access_group_added가 뒤바뀌어 도착할 수 있습니다. 어느 쪽이 먼저인지 알아내려면 초 단위로 정확한 occurred_at을 사용하세요.
• 드물게 유실될 수 있습니다. 이벤트는 데이터가 커밋된 뒤에 큐에 들어가므로, 그 두 단계 사이에 프로세스가 종료되면 이벤트가 유실됩니다.
• 상태를 동기화한다면 정합성을 맞추세요. 이벤트는 무언가 바뀌었다는 신호로 취급하고, 현재 상태는 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이나 빈 문자열이 아닙니다.
• 필드와 enum 값은 추가만 되고 변경되지 않습니다. 수신 측은 새로 추가된 값을 허용해야 합니다.

전체 이벤트