API 주문 완료 알림 설정 방법

어떤 이벤트를 주문 완료로 간주할지

먼저 API에서 어떤 상태가 주문의 실제 완료를 의미하는지 정하세요. 공급업체마다 완료, 배송됨, 취소됨, 거부됨, 반품됨 또는 부분 완료 주문일 수 있습니다. 자동화를 '성공'이라는 단어에만 연결하지 마세요. 주문은 여러 중간 상태를 거친 후 한도, 검토 또는 취소로 인해 중단될 수 있습니다.

긍정적인 결과만 처리해서는 안 됩니다. 서비스에서 오류, 취소, 반품 또는 부분 완료 알림을 보내는 경우에도 내부 시스템에 기록해야 합니다. 그렇지 않으면 패널, CRM 또는 봇에서 주문이 대기 상태로 남아 있지만 추가 실행은 이미 발생하지 않습니다.

상태 매핑 테이블 작성

처리 없이 API 상태를 인터페이스에 전달하지 마세요. 공급업체의 이름과 로직은 변경될 수 있으며, 동일한 내부 상태가 여러 외부 상태를 통합하는 경우도 있습니다. 원본 값을 별도로 저장하세요. 오류 분석 및 문서 대조에 유용합니다.

• pending, created, queued — 신규 또는 처리 대기 중인 주문.
• processing, in_progress, running — 주문 처리 중.
• completed, delivered, success — 완료된 주문.
• partial, partially_completed — 부분 완료된 주문.
• cancelled, rejected, failed — 취소되었거나 오류로 종료된 주문.
• refunded, returned — 반품 또는 조정이 필요한 주문.
• 알 수 없는 상태 — 카드를 자동으로 변경하지 않고 검토로 전달.

위 이름은 예시 스키마입니다. 최종 테이블은 특정 API의 상태에 따라 작성해야 합니다. 수동 매핑의 단점은 API 업데이트 후 유지 관리가 필요하다는 것입니다. 새 상태가 해당 규칙이 생성되기 전에 핸들러에 도달할 수 있습니다.

웹훅, API 폴링 또는 두 가지 방식 모두 선택

웹훅은 주문 상태 변경 시 서비스가 귀하의 URL로 보내는 요청입니다. API 폴링은 반대로 시스템이 일정 간격으로 주문 정보를 요청합니다. 완료 알림의 경우 상태 확인 메서드에 지속적으로 요청하지 않고 업데이트가 수신되므로 일반적으로 웹훅이 더 편리합니다.

• 웹훅은 빠른 반응(카드 업데이트, 다음 단계 시작 또는 담당자에게 메시지 전송)에 적합합니다.
• 폴링은 공급업체가 콜백 알림을 지원하지 않거나 서버가 외부 요청을 수락하지 않는 경우에 적합합니다.
• 결합 방식은 웹훅을 기본 채널로 사용하고 폴링은 누락되거나 지연된 주문을 찾는 데 사용합니다.

폴링의 단점은 지연과 API에 대한 추가 부하입니다. 웹훅의 단점은 엔드포인트를 보호하고 중복을 고려하며 이벤트 전송 순서에 의존하지 않아야 한다는 것입니다.

이벤트 수신을 위한 엔드포인트 설정

알림을 위해서는 API 서비스 측에서 액세스할 수 있는 공개 HTTPS 주소가 필요합니다. 통합 설정에서 일반적으로 핸들러 URL, 서명 시크릿 및 이벤트 목록(상태 변경, 완료, 취소, 오류 또는 부분 완료)을 지정합니다.

API 이벤트 전용 별도 경로를 할당하세요. 이렇게 하면 로깅을 설정하고, 액세스를 제한하고, 요청 한도를 설정하고, 서비스 트래픽을 사이트 양식과 혼합하지 않기가 더 쉽습니다. 운영 주문에 테스트 환경 주소를 사용하지 마세요. 환경 업데이트 후 공급업체는 저장된 URL로 이벤트를 계속 전송합니다.

시작 전에 문서에 따라 요청 메서드와 본문 형식을 확인하세요. 대부분 POST와 JSON이지만 form-data, 쿼리 매개변수 또는 사용자 지정 직렬화 스키마가 있을 수 있습니다. 구문 분석 오류를 로그에 기록해야 합니다. 그렇지 않으면 잘못된 페이로드와 애플리케이션 오류를 구별하기 어렵습니다.

주문과 이벤트 간의 연결 저장

API를 통해 주문을 생성할 때 공급업체가 반환한 식별자를 저장하세요. 내부 주문 번호, 서비스 유형, 원본 상태, 마지막 변경 시간 및 원본 API 응답을 안전한 형태로 함께 저장하세요. 수신 웹훅은 채널 링크, 서비스 이름 또는 고객 이름이 아닌 공급업체 ID로 매핑하세요.

API가 생성 시 외부 식별자 전달을 허용하는 경우 external_id 또는 client_reference와 같은 필드에 주문 번호를 추가하세요. 이렇게 하면 로그 검색 및 분쟁 상황 분석이 간소화됩니다. 그러나 외부 번호를 유일한 키로 사용하지 마세요. 일부 공급업체는 모든 알림에서 이를 반환하지 않습니다.

웹훅의 알 수 없는 ID로 새 주문을 생성하지 마세요. 알 수 없는 이벤트는 로그에 저장하고 별도로 확인해야 합니다. 자동 레코드 생성은 잘못된 데이터 또는 위조 요청 처리로 이어질 수 있습니다.

명확한 페이로드 구조 사용

정확한 필드 이름은 API에 따라 다릅니다. 아래는 특정 서비스의 계약이 아니라 내부 핸들러 설계 시 참고할 수 있는 JSON 이벤트 예시입니다. 이벤트 식별자, 공급업체 주문 ID, 상태, 변경 시간 및 진단 데이터가 중요합니다.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

상태 없이 완료된 단위 수를 완료 표시로 사용하지 마세요. 주문이 부분적으로 완료될 수 있으며 페이로드의 숫자는 반올림되거나 지연 업데이트되거나 전혀 전달되지 않을 수 있습니다. 전체 이벤트 본문 저장의 단점은 개인 데이터 또는 서비스 필드가 포함될 수 있으므로 이러한 레코드를 마스킹하고 보존 기간을 제한해야 한다는 것입니다.

원본 요청 본문으로 서명 확인

공개 핸들러 URL은 API 서비스뿐만 아니라 다른 곳에서도 요청을 받을 수 있습니다. 공급업체가 서명, 시크릿 또는 토큰을 전달하는 경우 주문을 변경하기 전에 확인하세요. 일반적인 방식은 HMAC-SHA256입니다. 공급업체는 요청 본문 바이트와 공유 시크릿으로 서명을 계산한 다음 결과를 HTTP 헤더로 전달합니다.

계산 원리는 다음과 같습니다. 원본 요청 본문(예: 변경되지 않은 JSON 바이트)과 통합 시크릿을 가져옵니다. 그런 다음 HMAC-SHA256을 계산합니다. 16진수 결과가 헤더 값과 일치하면 서명 후 본문이 변경되지 않았으며 요청은 시크릿을 아는 측에서 전송되었을 가능성이 높습니다.

조건부 예시: HMAC_SHA256(시크릿, raw_body) = X-Signature 헤더의 서명. 헤더 이름, 알고리즘 및 결과 형식은 API 문서에서만 가져와야 합니다. 일부 서비스는 서명 문자열에 타임스탬프 또는 이벤트 ID를 추가합니다. 이 경우 JSON 본문만 확인할 수 없습니다.

서명 확인 전에 JSON 변경 금지

서명은 애플리케이션이 이미 구문 분석하고 다시 조립한 JSON 객체가 아닌 원본 요청 바이트로 확인합니다. 재직렬화 시 필드 순서, 공백, 문자 이스케이프, 줄 바꿈 또는 인코딩이 변경될 수 있습니다. 사람에게는 JSON이 동일하게 보이지만 바이트 집합이 변경되어 HMAC이 일치하지 않습니다.

이를 방지하려면 먼저 raw body를 bytes 또는 buffer로 가져와 메모리에 저장하고 서명을 계산한 다음 성공적인 확인 후에만 JSON을 구문 분석하세요. 본문에 trim, 인코딩 변환, 키 정렬 및 서식을 적용하지 마세요. 프레임워크 미들웨어에서 원본 본문에 액세스하기 전에 JSON이 자동으로 구문 분석되는지 확인하세요.

이 방식의 단점은 핸들러가 미들웨어 순서에 의존하게 된다는 것입니다. 잘못 구성하면 애플리케이션은 변환된 객체만 보게 되고 정당한 알림이 거부되기 시작합니다.

HMAC 확인이 포함된 핸들러 예시

아래는 Python의 조건부 예시입니다. 완성된 통합이 아니라 작업 순서를 보여줍니다. 헤더, 알고리즘, 서명 형식 및 페이로드 필드는 공급업체 문서의 값으로 대체해야 합니다.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

비교에는 첫 번째 불일치 문자에서 중단되지 않는 함수를 사용하세요. 이렇게 하면 응답 시간을 통한 서명 데이터 유출 위험이 줄어듭니다. 시크릿을 클라이언트 코드에 전달하거나 URL에 추가하거나 로그에 전체를 기록하지 마세요.

이벤트 처리를 멱등적으로 만들기

공급업체는 동일한 이벤트를 여러 번 전송할 수 있습니다. 이유는 일반적입니다. 서버가 오래 응답했거나, 데이터 저장 후 연결이 끊어졌거나, 엔드포인트가 일시적으로 오류를 반환했거나, 서비스가 자체 규칙에 따라 재전송을 시작했습니다. 재전송은 API가 새 주문을 생성했다는 의미가 아닙니다.

멱등성은 동일한 이벤트가 결과를 한 번만 변경함을 의미합니다. 이 규칙을 고려하지 않으면 중복이 고객에게 메시지를 다시 보내거나, 관리자에게 여러 작업을 생성하거나, 보상을 지급하거나, 반복 작업을 시작합니다.

페이로드의 event_id를 사용하는 것이 가장 좋습니다. 별도 테이블이나 처리된 이벤트 로그에 고유 제약 조건과 함께 저장하세요. 별도 ID가 없는 경우 공급업체 주문 ID, 이벤트 유형, 상태 및 변경 시간과 같은 안정적인 필드로 키를 구성하세요. 이 옵션은 더 나쁩니다. 부정확한 타임스탬프의 경우 다른 이벤트가 동일하게 보일 수 있습니다.

단일 작업으로 이벤트 및 상태 저장

이벤트 처리 여부 확인과 결과 기록은 원자적으로 수행되어야 합니다. 그렇지 않으면 동시에 도착한 두 개의 동일한 요청이 모두 레코드 부재를 확인하고 작업을 두 번 시작합니다. 실용적인 옵션은 event_id에 대한 고유 인덱스와 데이터베이스 트랜잭션입니다.

핸들러의 조건부 연속은 다음과 같습니다.

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

알 수 없는 주문에 성공 코드로 응답하는 것의 단점은 공급업체가 전송을 반복하지 않을 수 있다는 것입니다. 따라서 알 수 없는 이벤트는 별도로 모니터링하고 신속하게 분석해야 합니다. API 문서에서 이러한 경우에 다른 응답 코드를 권장하는 경우 이를 따르세요.

이벤트 순서 위반 고려

웹훅이 항상 상태 변경 시간 순서대로 도착하지는 않습니다. 먼저 완료 이벤트가 도착한 다음 지연된 '처리 중' 상태 알림이 도착할 수 있습니다. 마지막으로 수신된 값만 기록하면 완료된 주문이 다시 활성화됩니다.

허용된 전환을 정의하세요. 예를 들어 중간 상태는 최종 상태를 덮어쓸 수 없으며 취소된 주문은 별도 확인 없이 완료로 전환되지 않습니다. API가 최종 상태 조정을 허용하는 경우 이유, 원본 값 및 변경 소스를 저장하세요.

페이로드에 주문 변경 시간이 포함된 경우 웹훅 수신 시간이 아닌 해당 시간을 비교하세요. API가 이러한 표시를 전달하지 않는 경우 상태 우선순위와 주문 가져오기 메서드를 통한 대조를 사용하세요. 우선순위의 단점은 실제 순서를 대체하지 않는다는 것입니다. 특히 공급업체가 최종 상태에서 반품을 허용하는 경우 더욱 그렇습니다.

전송을 신속하게 확인하고 작업을 대기열로 이동

공급업체에 응답하기 전에 긴 작업을 수행하지 마세요. 서명 확인, 주문 검색, 이벤트 기록 및 상태 업데이트는 일반적으로 신속하게 완료할 수 있습니다. 메시지 전송, CRM 동기화, 보고서 생성 또는 타사 시스템 요청은 작업 대기열로 전달하는 것이 좋습니다.

작업 순서는 다음과 같습니다. 서명 확인, 이벤트 및 상태 변경을 원자적으로 저장, 성공 응답 반환, 그런 다음 보조 작업 수행. 저장 전에 응답하면 실패 시 데이터가 손실됩니다. 긴 알림 전송 후 응답하면 공급업체가 전송을 실패로 간주하고 중복을 보낼 수 있습니다.

대기열의 단점은 모니터링해야 하는 별도 구성 요소(작업 오류, 지연 및 재실행)가 나타난다는 것입니다. 그러나 관리자 알림의 실패가 주문 상태 수신을 차단하지는 않습니다.

팀 및 고객을 위한 알림 설정

상태 변경 후 모든 사람에게 동일하게 알릴 필요는 없습니다. 관리자에게는 일반적으로 취소, 오류, 부분 완료 및 오랫동안 변경되지 않은 주문이 중요합니다. 고객에게는 명확한 결과(주문 완료, 취소 또는 확인 필요)로 충분한 경우가 많습니다.

• 완료된 주문 — 개인 계정 업데이트 또는 고객에게 간단한 메시지.
• 실행 오류 — API가 전달한 이유와 함께 담당자에게 알림.
• 부분 완료 — 조정, 반품 또는 다음 조치 확인 작업.
• 알 수 없는 상태 — 로그 기록 및 기술 전문가에게 메시지.
• 알 수 없는 주문 ID — 시스템과 공급업체 간의 연결 별도 확인.

모든 기술적 전환마다 메시지를 보내지 마세요. 피드가 빠르게 노이즈로 변하고 중요한 문제가 눈에 띄지 않게 됩니다. 내부 알림에는 주문 번호, 서비스, 현재 상태, 외부 ID 및 카드 링크가 포함되어야 합니다.

로그 유지 및 미완료 주문 대조

로그는 서비스가 이벤트를 보냈는지, 어떤 본문이 도착했는지, 서명이 실패한 이유 및 처리가 어느 단계에서 중단되었는지 이해하는 데 필요합니다. 수신 시간, 이벤트 ID, 주문 ID, 이벤트 유형, 서명 확인 결과, 내부 상태 및 응답 코드를 저장하세요. 시크릿, 토큰 및 개인 데이터를 마스킹하세요.

전송 오류, 유효하지 않은 서명, 알 수 없는 주문, 지원되지 않는 상태, 중복 및 상태 순서로 인해 적용할 수 없는 이벤트를 별도로 추적하세요. 이러한 레코드의 증가는 API 스키마 변경, 만료된 시크릿, 경로 오류 또는 핸들러 로직 오류를 의미할 수 있습니다.

API 데이터 가져오기 메서드를 통해 중간 상태의 주문을 주기적으로 대조하세요. 이 확인은 웹훅을 대체하지 않지만 누락된 이벤트, 대기열 오류 또는 외부 상태가 올바른 알림 없이 변경된 경우를 발견하는 데 도움이 됩니다.