주요 콘텐츠로 건너뛰기

웹훅 개요

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 또는 5xx (오류): 이 코드들은 재시도 일정 에 따라 재시도 시퀀스를 트리거합니다. 재시도가 실패하면, 아가님은 시도를 중지하며, 이벤트는 손실됩니다.

재시도 일정

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. 점(.)을 사용하여 타임스탬프와 원시 페이로드를 연결하여 서명 데이터를 형성합니다. Python 예시:

    signature_data = timestamp + '.' + raw_payload

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

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

    computed_signature = hmac_sha256(secret_key, signature_data)
정보

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

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

    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()

이벤트 유형 및 함수 동작

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

도움이 필요하세요?
통합팀에 문의하십시오 integration@aghanim.com

On this page