웹훅
이벤트를 빠르게 받고, 진짜인지 확인한 뒤, 한 번만 처리하세요.
수신한 이벤트를 원본 그대로 검증하고, 오래된 이벤트는 거절하고, 빠르게 응답한 뒤, 각 이벤트를 한 번만 처리하세요.
연동 구현 체크리스트
원본 그대로 읽기
서명을 확인하기 전에는 본문을 해석하거나 변형하지 마세요.
시각과 서명 확인
시각이 오래되었거나 발급된 비밀키와 맞지 않는 서명은 거부합니다.
빠르게 응답
오래 걸리는 작업을 시작하기 전에, 문서에 정해진 성공 응답부터 돌려보냅니다.
중복 제거
이벤트 ID를 "한 번만 처리"의 기준으로 삼아 저장합니다.
요청과 처리 결과
Saleringo-Event-Id: evt_...
Saleringo-Delivery-Timestamp: 2026-08-18T00:00:00Z
Saleringo-Delivery-Signature: v1=...verify(rawBody, timestamp, signature)
storeOnce(eventId)
enqueue(parsedEvent)
return acceptedResponse()오류별 대응 방법
| 상태 | 의미 | 연동 측 조치 |
|---|---|---|
| 401 | 인증 정보가 없거나 만료되었거나 올바르지 않음 | 요청을 중지하고 승인된 서버 절차로 인증 정보를 갱신합니다. |
| 403 | 요청한 작업에 필요한 권한 또는 범위가 없음 | 다시 시도하지 말고 접근 권한 검토를 요청합니다. |
| 409 | 상태, 버전, 중복 처리 방지 키, 승인 상태가 충돌함 | 충돌 내용을 확인하고 상태를 맞춘 뒤 다음 요청을 보냅니다. |
| 422 | 요청 형식이 공개된 스키마와 일치하지 않음 | 오류에 표시된 필드를 수정한 뒤 다시 요청합니다. |
| 429 | 짧은 시간에 요청을 너무 많이 보냄 | 응답에 안내된 대기 시간에 맞춰 요청 간격을 늘립니다. |
| 5xx | 일시적인 서비스 오류가 발생했을 수 있음 | 요청 ID를 보관하고 해당 작업이 재시도를 허용할 때만 다시 시도합니다. |