Webhook 가이드

Payload format

{
  "eventType": "PAYMENT_STATUS_CHANGED",
  "createdAt": "2026-04-21T10:20:00+09:00",
  "secret": "whsec_live_or_test_value",
  "data": { ... }
}

PAYMENT_STATUS_CHANGED

{
  "eventType": "PAYMENT_STATUS_CHANGED",
  "createdAt": "2026-04-21T10:20:00+09:00",
  "secret": "whsec_123",
  "data": {
    "paymentKey": "pay_123",
    "orderId": "order-001",
    "status": "DONE",
    "approvedAt": "2026-04-21T10:19:58+09:00"
  }
}

DEPOSIT_CALLBACK

{
  "eventType": "DEPOSIT_CALLBACK",
  "createdAt": "2026-04-21T10:30:00+09:00",
  "secret": "whsec_123",
  "data": {
    "paymentKey": "pay_va_123",
    "accountNumber": "140-123-456789",
    "depositedAmount": 25000,
    "status": "DONE"
  }
}

CANCEL_STATUS_CHANGED

{
  "eventType": "CANCEL_STATUS_CHANGED",
  "createdAt": "2026-04-21T11:00:00+09:00",
  "secret": "whsec_123",
  "data": {
    "paymentKey": "pay_123",
    "status": "CANCELED",
    "cancelAmount": 15000,
    "reason": "고객 요청"
  }
}

Signature verification

HMAC 서명이 아니라 본문 안의 `secret` 필드를 검증합니다. 문자열 비교는 `timingSafeEqual`을 사용해 길이와 값을 함께 확인하세요.

import { NextRequest, NextResponse } from "next/server";
import { timingSafeEqual } from "node:crypto";

function safeEqual(a: string, b: string) {
  const left = Buffer.from(a);
  const right = Buffer.from(b);
  return left.length === right.length && timingSafeEqual(left, right);
}

export async function POST(request: NextRequest) {
  const payload = await request.json();
  const webhookSecret = process.env.FAKETOSS_WEBHOOK_SECRET || "";

  if (!safeEqual(payload.secret || "", webhookSecret)) {
    return NextResponse.json({ code: "INVALID_SECRET" }, { status: 401 });
  }

  return NextResponse.json({ received: true });
}