주요 콘텐츠로 건너뛰기

웹훅 개요

Aghanim은 Aghanim이 생성한 게임 허브 내에서 플레이어가 트리거한 이벤트를 게임에 알리기 위해 웹후크를 사용합니다. 이러한 웹훅은 Aghanim과 귀하의 게임 간의 필수적인 통신을 용이하게 합니다. 이 가이드는 Aghanim 웹훅의 작동 방식과 구조를 설명합니다.

웹훅은 Aghanim 계정의 Game → Webhooks → New Webhook에서 지정한 URL로 Aghanim이 보내는 HTTP 콜백입니다. 특정 이벤트에 의해 활성화되는 이러한 요청은 관련 이벤트 데이터가 포함된 JSON 페이로드를 전송합니다.

웹훅 일반 흐름 이미지
웹훅 일반 흐름 이미지

스키마

Aghanim 서비스는 HTTP POST 요청을 웹훅 서버에 보내며, 다음과 같이 이벤트 데이터로 구조화된 JSON 페이로드를 포함합니다:

{
  "event_type": "player.verify",
  "event_data": {"player_id": "2D2R-OP3C"},
  "event_time": 1725534306,
  "event_id": "whevt_eBZXsUEITGeDcILaZFUvPthxkr",
  "idempotency_key": null,
  "sandbox": false,
  "trigger": "hub.login",
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "transaction_id": "whtx_eBZXsUEITGeDcILaZFUvPthxkr",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

이벤트 스키마

Key유형설명
event_idstringAghanim에 의해 생성된 고유 이벤트 ID.
game_idstringAghanim 시스템에서의 귀하의 게임 ID.
event_typestring이벤트 유형: 가능한 값은 다음과 같습니다: player.verify, item.add, item.remove, order.paid, order.canceled, order.refunded, coupon.redeemed, ingame.push, ingame.popup.
event_timenumber유닉스 에포크 시간으로 된 이벤트 날짜.
event_dataobject이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
idempotency_keystring|null웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다. 일 수 있습니다 null 이벤트 유형에 따라 달라집니다.
request_idstring|null이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
sandboxboolean이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
triggerstring|nullThe trigger that caused the event to be sent.
transaction_idstringAghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
contextobject|null이벤트에 대한 컨텍스트 정보.

웹훅 통합 설정

Aghanim에서 이벤트를 관리하려면 하나 이상의 함수를 개발해야 합니다. 모든 이벤트를 단일 엔드포인트를 통해 처리할 수도 있고, 각각 특정 이벤트나 다른 로직에 전담된 여러 엔드포인트를 사용할 수도 있습니다.

요구 사항

귀하의 함수는 다음 요구 사항 및 논리를 따라야 합니다:

  • POST 웹훅 요청을 수락하는 HTTPS 엔드포인트.
  • Aghanim이 생성하고 서명한 이벤트를 수신합니다.
  • 중복된 웹훅 처리를 방지하기 위해 웹훅 페이로드에 포함된 idempotency_key를 처리합니다.
  • 플레이어 ID를 기준으로 Game Hub 접근 권한을 결정하기 위해 데이터베이스에서 플레이어를 확인하거나, 구매한 아이템을 플레이어 계정에 지급하는 등, 수신된 요청을 적절하게 처리하십시오.
  • 액세스 승인 또는 항목에 대한 크레딧이 제공된 경우 2xx 상태 코드로 응답하고, 거부 또는 오류의 경우 4xx 또는 5xx로 응답합니다.

Aghanim에서 엔드포인트 등록

  1. 엔드포인트를 사용 가능하게 설정하세요.
  2. 원하는 이벤트를 선택하여 Aghanim 계정 → Game → Webhooks → New Webhook 내에서 엔드포인트를 등록하세요.
  3. 생성된 비밀 키를 복사하여 요청 서명 검증을 위해 웹훅 함수에 지정하세요.

대안으로, 웹후크 생성 API 방법을 사용하여 Aghanim 내에서 엔드포인트를 등록할 수 있습니다.

이벤트에 대응하기

웹훅에 대한 응답으로 Aghanim은 다음을 기대합니다:

  • 2xx (성공): 이 코드는 웹훅 함수가 기대된 논리에 따라 이벤트를 성공적으로 처리했음을 나타냅니다.
  • 4xx (클라이언트 오류): 동작은 웹훅 유형에 따라 달라집니다:
    • 대부분의 웹훅에서 이러한 코드는 재시도 시퀀스를 트리거합니다. 재시도가 실패하면, 아가님은 시도를 중지하며, 이벤트는 손실됩니다.
    • 일부 웹훅은 재시도 대신 특정 동작을 트리거하는 구조화된 JSON 페이로드와 함께 특정 오류 응답 코드를 정의합니다. 자세한 내용은 각 웹훅 문서를 참조하세요(예: Player Verify).
  • 5xx (서버 오류): 이러한 코드는 일시적인 서버 측 장애(예: 데이터베이스 사용 불가, 내부 예외)를 나타냅니다. Aghanim은 재시도 일정에 따라 이러한 요청을 자동으로 재시도합니다.

재시도 일정

Aghanim은 웹훅 메시지가 전달되도록 지수적으로 백오프 전략을 사용합니다. 초기 전달 시도가 실패할 경우, Aghanim은 다음 순서에 따라 다시 시도합니다:

  • 실패 직후
  • 5초 후
  • 5분 후
  • 30분 후
  • 2시간 후
  • 5시간 후
  • 10시간 후
  • 또 다른 10시간 후
  • 모든 재시도가 실패하면, 메시지 전달이 포기됩니다

예를 들어, 웹훅 메시지가 세 번 연속으로 전달에 실패하면, 성공적인 전달은 초기 시도 후 약 35분 5초 후에 이루어질 것입니다.

Idempotency

Aghanim은 다음 웹훅에 idempotency_key를 포함하여 게임 측에서 동일한 작업이 두 번 트리거되지 않도록 안전하게 요청을 재시도합니다:

이러한 웹훅을 처리할 때 idempotency_key의 고유성을 활용하여 작업이 한 번만 실행되도록 보장합니다:

  • 웹훅에 포함된 고유한 idempotency_key를 처음 수신한 경우에만, 아이템 지급 등 예상된 동작을 수행하세요.
  • 동일한 idempotency_key를 가진 웹훅을 다시 수신하면 이를 무시하고 200 상태 코드로 응답합니다.

예를 들어, 연결 오류가 발생하고 Aghanim이 웹훅 전송을 재시도하는 경우 idempotency_key는 동일하게 유지됩니다. 이로 인해 게임 측에서의 동작이 한 번만 실행되도록 보장되며, 예기치 않은 부작용 없이 요청을 반복적으로 전송할 수 있습니다.

Secure 웹훅

각 Aghanim 요청에는 요청의 진위 여부를 확인할 수 있는 고유한 비밀 키 기반의 서명이 포함되어 있습니다. 웹훅 이벤트에는 보안 검사를 위한 특정 헤더가 포함됩니다:

  • X-Aghanim-Signature: 이벤트 페이로드의 HMAC-SHA256 서명.
  • X-Aghanim-Signature-Timestamp: 이벤트가 발생한 정확한 Unix epoch 시간.

요청의 무결성을 확인하려면:

  1. 수신된 이벤트에서 원시 페이로드 및 X-Aghanim-Signature-Timestamp 헤더를 추출합니다.

  2. 점(.)을 사용하여 타임스탬프와 원시 페이로드를 연결하여 서명 데이터를 형성합니다. 문자열로의 변환 또는 JSON 파싱과 같은 역직렬화 없이 HTTPS 요청 페이로드의 원시 바이트를 사용해야 합니다. 의사 코드 예시:

    signature_data = timestamp + '.' + raw_payload

  3. Aghanim 계정 → Game → Webhooks → 해당 웹훅에서 고유한 시크릿 키를 가져옵니다.

  4. 비밀 키를 사용하여 HMAC-SHA256 해시를 생성합니다. 예를 들어:

    computed_signature = hmac_sha256(secret_key, signature_data)
    정보

    계산된 서명은 16진수(hexadecimal) 형식으로 표현하세요.

  5. 수신된 이벤트의 X-Aghanim-Signature 헤더와 computed_signature를 비교합니다. 일치하면 해당 이벤트가 신뢰할 수 있는 출처에서 나온 것으로 확인됩니다. 의사 코드 예시:

    signature_data = timestamp + '.' + raw_payload
    computed_signature = hmac_sha256(secret_key, signature_data)

    # Compare the computed_signature and received_signature
    if computed_signature == received_signature:
     # Signature is valid
     process_webhook_event(raw_payload)
    else:
     # Signature is invalid
     ignore_webhook_event()

방화벽 사용

디지털 서명의 사용은 요청의 보안을 보장합니다. 그러나 보안 정책상 방화벽으로 엔드포인트를 보호해야 하는 경우, 이를 구성할 수 있습니다. 웹훅 요청을 보내는 데 사용되는 IP 주소 목록은 요청 시 제공됩니다. 목록을 얻으려면 팀에 문의하십시오.

배치 모드

대량 이벤트 유형(예: analytics)의 경우 webhook에서 배치 모드를 활성화할 수 있습니다. 개별 HTTP 요청을 받는 대신, 이벤트가 일정 시간 창 동안 수집된 후 다운로드 가능한 JSONL 파일로 전달됩니다. 설정 및 자세한 내용은 Webhook Batch Export를 참조하세요.

이벤트 유형 및 함수 동작

Aghanim은 다음과 같은 유형의 이벤트를 제공합니다. 이러한 이벤트 발생 시 함수가 어떻게 반응해야 하는지와, 각 이벤트의 목적 및 내용을 알아보세요:

도움이 필요하세요?
통합팀에 문의하십시오 [email protected]

On this page