Webhook 테스터

Webhook 테스트서명을 확인하세요

예시 본문을 편집하고 HMAC-SHA256 서명과 cURL 요청을 생성해 테스트 환경에서 검증 로직을 확인하세요.

Webhook 서명 작업 공간

테스트 설정, 본문 편집, 서명과 요청 복사.

테스트 설정

주소, 테스트 키, 타임스탬프를 입력하세요.

Webhook 주소

테스트 키

서명은 브라우저에서 계산됩니다. 테스트 키를 사용하세요.

타임스탬프(ms)

BoltUtil 헤더와 동일한 밀리초 단위 Unix 타임스탬프입니다.

본문 편집 및 서명 생성

JSON을 편집하면 서명과 cURL이 함께 업데이트됩니다.

서명

HMAC-SHA256

유효한 키, 타임스탬프, JSON을 입력하세요.

현재 타임스탬프, 원문 본문, 테스트 키로 계산됩니다.

webhook_payload.json유효한 JSON
{
  "externalOrderId": "ORDER_100001",
  "status": "CONFIRMED",
  "amount": "199.001",
  "paidAmount": "199.001",
  "shortfallAmount": "0",
  "settlementType": "EXACT",
  "manuallyAccepted": false,
  "currency": "USDC",
  "network": "BASE",
  "destinationAddress": "0x1111111111111111111111111111111111111111",
  "txHash": "0x1111111111111111111111111111111111111111111111111111111111111111",
  "confirmations": 20,
  "paidAt": "2026-10-07 12:30:00",
  "confirmedAt": "2026-10-07 12:35:00",
  "completedAt": "2026-10-07 12:35:00",
  "metadata": {
    "reference": "demo"
  }
}

cURL / POST테스트 요청

유효한 주소, 키, 타임스탬프, JSON을 입력하세요.

USDC 주문의 모의 콜백이며 USDT로 변경할 수 있습니다. 주문, 주소, 거래 해시는 예시로 실제 결제 증거가 아닙니다.

이 도구는 요청을 보내지 않습니다. 테스트 환경에서 cURL을 직접 실행하세요.

서명 검증

계속하기 전에 검증

같은 규칙으로 검증하고 이벤트를 저장한 뒤 주문을 업데이트하세요.

서명 검증 가이드

HMAC_SHA256(timestamp + "." + rawBody, secret)

01
원시 본체 확인
JSON를 구문 분석하기 전에 헤더의 밀리초 타임스탬프와 정확한 원시 본문을 사용하여 HMAC를 계산하세요. 공백, 줄 바꿈 및 필드 순서가 서명에 영향을 미칩니다.
02
타이밍 안전 비교 사용
수신된 서명을 언어 런타임에서 제공하는 상수 시간 도우미와 비교하세요.
03
안전하게 녹음한 후 2xx를 반환하세요.
이벤트를 기록하거나 내구성 있는 내부 대기열에 넣은 후에만 성공을 반환합니다.

Webhook 문제 해결

일치하지 않습니까? 여기서 시작하세요

문제를 찾으려면 원본 본문, 비밀글, 응답 상태를 확인하세요.

서명 불일치

가장 일반적인 원인은 정확한 원시 본문 대신 구문 분석된 JSON에 서명하거나 요청 헤더와 다른 타임스탬프를 사용하는 것입니다.

잘못된 비밀

판매자 엔드포인트에 구성된 웹훅 비밀을 사용하세요. API 키와 웹훅 비밀은 다른 자격 증명으로 처리되어야 합니다.

본문 파서가 페이로드를 변경했습니다.

JSON 미들웨어는 페이로드를 재정렬하거나 형식을 다시 지정할 수 있습니다. HMAC 서명을 확인할 때 구문 분석하기 전에 원시 본문을 캡처하세요.

끝점은 2xx가 아닌 것을 반환합니다.

2xx가 아닌 응답은 전달 실패입니다. 재시도는 콜백 유형, HTTP 상태, 정책에 따라 달라집니다.

처리는 멱등성이 아닙니다.

주문 ID와 상태 또는 고유 이벤트 ID로 중복을 제거하세요. 한 거래 해시에 여러 송금이 포함될 수 있습니다.

내구성 이전의 성공

데이터베이스나 대기열에 이벤트를 쓴 후에만 HTTP 2xx를 반환합니다. 그렇지 않으면 충돌로 인해 완료된 결제 알림이 손실될 수 있습니다.

FAQ

디버깅 중 질문

서명 확인, 응답 및 중복 전달.

웹훅 서명 확인이 실패하는 이유는 무엇입니까?

정확한 원시 요청 본문, 타임스탬프 헤더, 구성된 웹훅 비밀을 확인하세요. 구문 분석된 JSON 또는 다시 포맷된 본문에 서명하면 일반적으로 다른 HMAC가 생성됩니다.

내 웹훅 엔드포인트가 응답 본문에 SUCCESS를 반환해야 합니까?

아니요. BoltUtil은 HTTP 상태로 판단하며 2xx는 수신 성공입니다. 먼저 검증하고 이벤트를 저장하세요.

중복된 웹훅 전달을 어떻게 처리해야 합니까?

주문 ID와 상태 또는 이벤트 ID에 고유 제약이나 원자적 연산을 사용하세요. 거래 해시만 사용하면 부족합니다.

엔드포인트는 언제 HTTP 2xx를 반환해야 합니까?

검증과 저장 후 2xx를 반환하세요. 실패하면 적절한 오류를 반환하며 재시도는 콜백 유형과 정책에 따릅니다.