Webhook 참조

요약

HTTPS 엔드포인트를 등록하면 주문 또는 결제 상태가 바뀔 때마다 Elim이 여러분의 시스템으로 직접 호출합니다. 상태를 계속 폴링할 필요가 없습니다. 이 페이지는 이벤트, 관리 엔드포인트, 페이로드 구조, 서명 검증, 재시도 정책을 다룹니다.

Webhook이 주문 수명 주기에서 차지하는 위치는 주문 가이드와 주문 API 참조를 참고하세요.

모든 엔드포인트는 JWT 인증(Authorization: Bearer <token>) 또는 API 키(x-api-key)가 필요합니다.

이벤트

구독한 이벤트만 수신합니다. 보통 둘 다 구독합니다.

구독 관리 엔드포인트

접두사 /v1/webhooks.

생성 본문

{
  "url": "https://your-system.example/webhooks/elim",
  "events": ["order.updated", "payment.updated"],
  "is_active": true
}

secret은 생성 또는 rotate-secret 직후에만 반환됩니다. 모든 요청을 검증하는 데 필요하므로 안전하게 보관하세요. secret을 분실하면 rotate-secret으로 재발급합니다(기존 서명은 즉시 무효화됩니다).

페이로드 구조

두 이벤트는 동일한 구조를 사용하며 event 필드만 다릅니다.

{
  "id": "evt_4a1f2c...",
  "event": "payment.updated",
  "created_at": "2026-06-19T00:00:00.000Z",
  "data": {
    "order": {
      "id": "ORD0000000123",
      "platform": "taobao",
      "order_id": "123456789",
      "status": "paid",
      "payment_status": "paid",
      "platform_payment_status": "success",
      "total_amount_cny": 123.45,
      "updated_at": "2026-06-19T00:00:00.000Z"
    }
  }
}

핸들러 처리: data.order.id로 주문을 조회하고 시스템의 주문 상태를 갱신한 뒤 HTTP 2xx를 반환합니다. 페이로드는 순서가 뒤바뀌어 도착할 수 있으므로, 항상 더 새로운 updated_at을 신뢰하고 이미 보유한 상태보다 오래된 이벤트는 무시하세요.

각 전송의 헤더

서명 검증

서명 문자열: "{X-Elim-Timestamp}.{원본 JSON 본문}" — 파싱 후 재직렬화하지 말고 수신한 원본 본문을 사용하세요.

알고리즘: HMAC-SHA256(secret, 서명 문자열), X-Elim-Signature의 sha256= 뒤 부분과 타이밍 안전 비교로 대조합니다.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyElimWebhook(
  secret: string,
  timestamp: string,
  rawBody: string,
  signature: string,
): boolean {
  const expected = `sha256=${createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')}`;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

재생 공격을 줄이기 위해 X-Elim-Timestamp가 현재와 너무 차이 나는(예: 5분 초과) 요청은 거부하세요.

재시도 정책

전송별 결과는 GET /v1/webhooks/:id/deliveries에서 확인합니다. POST /v1/webhooks/:id/test로 수신 설정을 빠르게 검증하세요.

보안

• 운영 환경 URL은 반드시 HTTPS여야 합니다. 개발 환경은 localhost 허용.
• 운영 환경에서는 사설/내부/메타데이터 IP가 차단됩니다.
• secret은 생성 또는 rotate-secret 이후에만 표시됩니다.
• 페이로드에는 비밀번호, API 키, JWT, 플랫폼 액세스 토큰이 포함되지 않습니다.

Webhook을 아직 설정하지 않았다면

GET /v1/orders/:id로 언제든 상태를 직접 조회할 수 있습니다. 호출할 때마다 Elim이 플랫폼에서 최신 상태를 동기화한 뒤 응답합니다. 주문 API 참조를 보세요.

관련 링크

• 주문 API 참조
• 주문 가이드
• 인증 가이드