웹훅

웹훅은 HTTPS 수신 주소로 보내는 선택적 서명 알림입니다. 상태 조회는 계속 가능하며 API 사용에 웹훅 설치가 필수는 아닙니다.

내 API 계정

API 계정에서 수신 주소를 켜세요. 공개 HTTPS/443만 지원하며 리디렉션, 쿼리 문자열, URL 인증 정보는 지원하지 않습니다. 주소, 활성화 또는 서명 키 변경 시 이전 대기 이벤트가 취소되며 과거 작업은 소급 전송하지 않습니다.

지원되는 새 API 작업만 관찰하며 모든 HTTP 응답이나 사이트 구매가 대상은 아닙니다. 알림에는 안전한 식별자와 상태만 포함되고 API 키나 프록시 비밀번호는 없습니다. timestamp는 로컬 UTC 관측 시각이며 분 단위 작업으로 지연될 수 있습니다.

이벤트 유형

유형	상태
`webhook.test`	`test`
`order.accepted`	`accepted`
`order.delivered`	`delivered`
`order.action_required`	`action_required`
`order.canceled`	`canceled`
`renewal.completed`	`completed`
`extra_login.operation.completed`	`completed`
`extra_login.operation.rejected`	`rejected`
`extra_login.operation.action_required`	`action_required`
`proxy_ip.operation.completed`	`completed`
`proxy_ip.operation.rejected`	`rejected`
`proxy_ip.operation.action_required`	`action_required`
`proxy_ip.authorization.revoked`	`revoked`
`residential_list.operation.completed`	`completed`
`residential_list.operation.rejected`	`rejected`
`residential_list.operation.action_required`	`action_required`
`auto_renewal.configuration.completed`	`completed`

application/json

{
    "id": "evt_0123456789abcdef0123456789abcdef",
    "type": "order.delivered",
    "timestamp": "2026-10-26T12:00:00+00:00",
    "api_version": "1",
    "data": {
        "account_id": 12345,
        "order_id": 12345,
        "number": "1000012345",
        "product": "proxy",
        "state": "delivered",
        "quantity": 1,
        "mode": null,
        "gb": null,
        "reason_code": null,
        "provider_live_check": false
    }
}

서명 검증

별도 웹훅 키로 webhook-id, webhook-timestamp, webhook-signature를 검증하세요. whsec_를 제거하고 Base64로 디코딩한 키로 아래 원본 본문 형식의 HMAC-SHA256을 계산해 상수 시간 비교를 하세요. 타임스탬프 허용 오차는 300초입니다.

HMAC-SHA256

signed_content = webhook_id + "." + webhook_timestamp + "." + raw_body
webhook_signature = "v1," + Base64(HMAC_SHA256(decoded_secret, signed_content))

전송 및 재시도

이벤트 ID별로 중복을 방지하세요. 알림은 중복되거나 순서 없이 올 수 있으며 수락 후 2xx를 반환하세요. 최대 7회 시도하며 간격은 1분, 5분, 30분, 2시간, 6시간, 24시간입니다. 알림만 재전송하며 실제 작업을 반복하지 않습니다.

HTTP 2xx는 전송 확인입니다. 408/429/5xx 및 일시적 네트워크 오류는 재시도될 수 있고 다른 4xx와 리디렉션은 영구 실패입니다. 재시도 시 이벤트 ID와 본문은 같고 서명 시각은 새로 생성됩니다.