개발자 · 웹훅

출금 라이프사이클을 위한 HMAC 서명 웹훅.

제품에 비동기 라이프사이클 상태가 필요한 경우 웹훅 엔드포인트를 등록하고 각 전달을 검증하세요. 서명은 타임스탬프를 정확한 원본 본문에 바인딩하므로 변조되거나 재전송된 페이로드를 거부할 수 있습니다.

라이프사이클 이벤트

이벤트	의미
deposit.created	Base에서 판매자 예치금이 생성되었습니다
deposit.partially_filled	예치금이 부분 체결되었습니다
deposit.filled	예치금이 완전히 체결되었습니다
deposit.closed	판매자가 잔여 잔액을 닫거나 인출했습니다
otc.taken	승인된 구매자가 비공개 OTC 예치금을 가져갔습니다

모든 전달 검증

1t=<unix>,v1=<hex> 형식으로 X-Usdctofiat-Signature 헤더를 읽으세요.
2파싱되지 않은 원본 본문을 사용하여 timestamp.rawBody 문자열로 서명 페이로드를 구성하세요.
3엔드포인트 시크릿으로 해당 페이로드에 대해 HMAC-SHA256을 계산하세요.
4이벤트를 신뢰하기 전에 v1 16진수 값과 상수 시간으로 비교하세요.
5선택적으로 선택한 창보다 오래된 타임스탬프의 전달을 거부하세요.

재전송 방지는 귀하의 선택입니다

스타터 저장소의 참조 수신기는 재전송을 방지하기 위해 5분보다 오래된 타임스탬프를 오래된 것으로 처리합니다. 이 창은 전송자가 아닌 검증자에 의해 적용되므로 지연 시간 및 재시도 허용 범위에 맞게 조이거나 늘릴 수 있습니다.

서명이 timestamp.rawBody를 포함하므로 HMAC 검사가 통과된 후에만 JSON을 파싱하세요. 원본 바이트 대신 파싱된 객체를 검증하는 것은 서명 검증을 미묘하게 잘못 구현하는 가장 일반적인 방법입니다.

등록 및 운영

Peerlytics API 키로 엔드포인트를 등록하세요. 하나의 키로 출금 및 Peerlytics 표면 모두를 인증합니다.
반복적인 연속 전달 실패가 발생한 엔드포인트는 수정할 때까지 비활성화될 수 있습니다.
스타터 저장소 수신기를 신뢰할 수 있는 HMAC 검증 참조로 사용하세요.
웹훅을 상태 힌트로 처리하고, 중요한 경우 deposits()로 온체인 진실과 조정하세요.

Keep exploring

Offramp SDK Developer hub

Common questions

USDCtoFiat 웹훅은 어떻게 서명되나요?

각 전달에는 X-Usdctofiat-Signature: t=<unix>,v1=<hex>가 포함되며, 이는 timestamp.rawBody 문자열에 대한 HMAC-SHA256입니다. 엔드포인트 시크릿으로 원본 본문에 대해 HMAC를 재계산하고, 이벤트를 신뢰하기 전에 상수 시간으로 비교하세요.

웹훅 재전송을 어떻게 방지하나요?

서명된 타임스탬프가 선택한 창보다 오래된 전달을 거부하세요. 참조 수신기는 5분을 사용합니다. 전송자는 창을 적용하지 않으므로 이는 검증자의 책임입니다.

웹훅에 API 키가 필요한가요?

네. 예치금 생성은 퍼미션리스이지만, 웹훅 엔드포인트 등록에는 Peerlytics API 키가 필요합니다. 동일한 키가 Peerlytics API도 인증합니다.