웹훅

웹훅을 통해 결제 완료 이벤트를 실시간으로 수신할 수 있습니다.

웹훅 설정

가맹점 대시보드에서 웹훅을 설정합니다.

1. 대시보드에 로그인합니다.
2. 프로젝트 선택 → 설정 → Webhooks 메뉴로 이동합니다.
3. Webhook URL을 등록합니다. (HTTPS 필수)
4. 발급된 Signing Secret(whsec_)을 안전하게 보관합니다.

Signing Secret 보관

Signing Secret은 생성 시 한 번만 표시됩니다. 분실 시 새로 발급받아야 하며, 외부에 노출되지 않도록 서버 사이드에서만 사용해야 합니다.

이벤트 타입

이벤트	설명
invoice.confirmed	결제 확인 (블록체인 입금 확정)

웹훅 페이로드

{
  "id": "webhook-event-uuid",
  "type": "invoice.confirmed",
  "createdAt": "2024-01-29T12:00:00Z",
  "data": {
    "invoiceId": "invoice-uuid",
    "clientInvoiceId": "ORDER-12345",
    "amount": "100.00000000",
    "tokenSymbol": "USDT",
    "networkName": "Ethereum",
    "txHash": "0xabc123...",
    "confirmedAt": "2024-01-29T12:00:00Z"
  }
}

필드	타입	설명
id	string	웹훅 이벤트 고유 ID (UUID)
type	string	이벤트 타입
createdAt	string	이벤트 생성 시각 (ISO 8601)
data.invoiceId	string	OOZOO 인보이스 ID
data.clientInvoiceId	string | null	가맹점에서 지정한 주문 ID
data.amount	string	결제 금액 (토큰 단위)
data.tokenSymbol	string | null	토큰 심볼 (예: USDT)
data.networkName	string | null	블록체인 네트워크 이름 (예: Ethereum)
data.txHash	string | null	블록체인 트랜잭션 해시
data.confirmedAt	string | null	확인 시각 (ISO 8601)

서명 검증

웹훅 요청의 X-Webhook-Signature 헤더에 HMAC-SHA256 서명이 포함됩니다. Signing Secret을 사용하여 요청의 무결성을 반드시 검증하시기 바랍니다.

import * as crypto from 'crypto';

function verifyWebhookSignature(rawBody: string, signature: string, signingSecret: string): boolean {
  const expectedSignature = crypto.createHmac('sha256', signingSecret).update(rawBody).digest('hex');

  return signature === expectedSignature;
}

// Express 예시
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const rawBody = req.body.toString();

  if (!verifyWebhookSignature(rawBody, signature, 'whsec_xxxxxxxx')) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);

  if (event.type === 'invoice.confirmed') {
    // 결제 확인 처리
    console.log('결제 확인:', event.data.invoiceId);
  }

  res.status(200).send('OK');
});

서명 검증 필수

서명 검증 없이 웹훅 이벤트를 처리하면 위조된 요청에 의해 피해를 입을 수 있습니다. 반드시 X-Webhook-Signature 헤더를 검증한 후 이벤트를 처리하시기 바랍니다.

재시도 정책

웹훅 전송 실패 시 자동으로 재시도합니다. 최대 5회까지 시도하며, 지수 백오프 방식으로 재시도합니다.

시도	대기 시간
1차	즉시
2차	1분 후
3차	2분 후
4차	4분 후
5차	8분 후

총 5회 시도 후에도 실패하면 해당 이벤트는 전송 실패로 기록됩니다. 가맹점 대시보드에서 전송 이력을 확인하고 수동으로 재전송할 수 있습니다.

응답 요구사항

항목	설명
상태 코드	2xx 응답 시 성공으로 처리됩니다. 그 외 상태 코드는 실패로 간주합니다.
타임아웃	10초 이내에 응답해야 합니다. 초과 시 실패로 처리됩니다.
멱등성	동일한 이벤트가 중복 전송될 수 있으므로, id 필드를 기준으로 멱등하게 처리해야 합니다.
Content-Type	요청 본문은 application/json 형식입니다.

웹훅 로그 조회

API를 통해 웹훅 전송 이력을 조회할 수 있습니다. 자세한 내용은 웹훅 로그 조회 API 문서를 참고하시기 바랍니다.