웹훅 개요

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

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

AI 어시스턴트로 웹훅 핸들러 구축하기

Aghanim의 AI 코딩 도구는 서명 검증, 멱등성, 테스트를 갖춘 Aghanim 웹훅 핸들러를 귀하의 프로젝트 스택에 맞게 스캐폴딩할 수 있습니다.

스키마

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_id	string	Aghanim에 의해 생성된 고유 이벤트 ID.
game_id	string	Aghanim 시스템에서의 귀하의 게임 ID.
event_type	string	이벤트 유형: 가능한 값은 다음과 같습니다: player.verify, item.add, item.remove, order.paid, order.canceled, order.refunded, coupon.redeemed, ingame.push, ingame.popup.
event_time	number	유닉스 에포크 시간으로 된 이벤트 날짜.
event_data	object	이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
idempotency_key	string|null	웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다. 일 수 있습니다 null 이벤트 유형에 따라 달라집니다.
request_id	string|null	이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
sandbox	boolean	이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
trigger	string|null	The trigger that caused the event to be sent.
transaction_id	string	Aghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
context	object|null	이벤트에 대한 컨텍스트 정보.

웹훅 통합 설정

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

요구 사항

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

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

Aghanim에서 엔드포인트 등록

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

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

이벤트에 대응하기

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

• 2xx (성공): 이 코드는 웹훅 함수가 기대된 논리에 따라 이벤트를 성공적으로 처리했음을 나타냅니다.
• 4xx (클라이언트 오류): 동작은 웹훅 유형에 따라 달라집니다:
  • 대부분의 웹훅에서 이러한 코드는 재시도 시퀀스를 트리거합니다. 재시도가 실패하면, 아가님은 시도를 중지하며, 이벤트는 손실됩니다.
  • 일부 웹훅은 재시도 대신 상태별 동작을 정의합니다. HTTP 상태 코드가 Aghanim의 반응을 결정하고, 구조화된 JSON 오류 본문이 결과를 세분화합니다. 자세한 내용은 각 웹훅 문서를 참조하세요(예: Player Verify).
  • 상태별 동작을 가진 웹훅의 경우, 일부 4xx 상태는 플레이어 수준의 거부가 아니라 통합 수준의 신호입니다. Player Verify의 경우, 400(validation_error, 요청 데이터가 유효하지 않음)과 401(invalid_signature, 웹훅 서명을 검증할 수 없음)은 플레이어를 로그아웃시키거나 플레이어에게 표시되는 메시지를 보여주지 않고 검증을 거부합니다. 로그인 시 플레이어는 단순히 입장이 거부되며, 백그라운드 재검증 중에는 아무런 조치도 취하지 않습니다.
• 5xx (서버 오류): 이러한 코드는 일시적인 서버 측 장애(예: 데이터베이스 사용 불가, 내부 예외)를 나타냅니다. Aghanim은 재시도 일정에 따라 이러한 요청을 자동으로 재시도합니다. 단, player.verify는 예외로, 동기적으로 전달되며 재시도되지 않습니다.

재시도 일정

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

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

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

player.verify는 재시도되지 않습니다

재시도 일정은 비동기 웹훅에만 적용됩니다. 예를 들어 item.add, item.remove, order.*, coupon.redeemed, subscription.*, fraud.reported 등입니다. player.verify 웹훅은 단일 시도로 동기적으로 전달되며 재시도되지 않습니다. 5xx 응답은 재시도 없이 해당 검증을 거부합니다. Player Verify를 참조하세요.

Idempotency

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

• 아이템 추가 (item.add)
• 아이템 제거(item.remove)
• 주문 결제 완료 (order.paid)
• 주문 생성 (order.created)
• 주문 환불 완료 (order.refunded)
• 주문 취소 (order.canceled)
• 쿠폰 사용됨 (coupon.redeemed)
• 구독 (subscription.*)
• 사기 신고됨 (fraud.reported)

이러한 웹훅을 처리할 때 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 웹훅은 관련되어 있지만 서로 다른 두 가지 개념을 전달합니다. event_type 필드는 무엇이 전송되는지를 식별합니다. 이는 아래의 문서 페이지에 해당하며 페이로드 형태를 결정합니다. trigger 필드는 무엇이 웹훅을 유발했는지를 식별합니다. 이는 Aghanim이 이벤트를 발행하게 만든 구체적인 동작(플레이어 활동, API 호출, LiveOps 동작 또는 테스트)입니다. 단일 트리거가 여러 이벤트 유형을 발행할 수 있으며, 단일 이벤트 유형이 여러 트리거에 의해 발행될 수도 있습니다.

아래 참조는 각 이벤트 유형에 대해 이를 유발할 수 있는 트리거를 나열합니다. 조건부 동작은 각주 번호로 표시되며 조건부 동작 참고에서 설명됩니다.

상위 호환성

지원되는 트리거 집합은 언제든지 늘어날 수 있습니다. 새로운 플랫폼 기능이 출시됨에 따라 Aghanim은 사전 통지 없이 새로운 trigger 값을 도입할 수 있습니다. 웹훅 핸들러를 알 수 없는 트리거에 견딜 수 있도록 구축하세요. 핵심 로직은 (안정적인) event_type을 기준으로 분기하고, 이 참조에 없는 trigger 값에 대해 절대로 거부하거나 충돌하지 마세요. 아래 목록은 스냅샷이며 닫힌 열거형이 아니라고 간주하세요.

플레이어 이벤트

Event type	Emitted by
player.verify	hub.login, hub.interact¹, hub.purchase⁴, hub.store.open³, order.captured⁴, s2s.user.authorize⁵, s2s.player.issue_loyalty_points⁵, liveops.execute_action, test
player.lookup	hub.login, test
player.is_idle	hub.login, liveops.execute_action, test
player.marketing_consent.updated	hub.purchase, s2s.player.marketing_consent.grant, s2s.player.marketing_consent.revoke, dashboard.player.marketing_consent.revoke, checkout_profile.player.marketing_consent.revoke, test

아이템 및 스토어 이벤트

Event type	Emitted by
item.add	coupon.redeemed, order.paid, hub.purchase, hub.free_item_claim, hub.daily_reward_claim, hub.loyalty_claim, hub.progression_reward_claimed, hub.rolling_offer_claimed, hub.pick_one_offer_claimed, hub.lootbox.open, checkout.purchase, liveops.execute_action, test
item.remove	order.canceled, order.refunded, checkout.cancel, checkout.refund, liveops.execute_action, test
store.get	hub.login², hub.store.open, hub.purchase, order.captured, test

주문 이벤트

Event type	Emitted by
order.created	hub.purchase, test
order.paid	checkout.purchase, test
order.canceled	checkout.cancel, test
order.refunded	checkout.refund, test

기타 핵심 이벤트

Event type	Emitted by
coupon.redeemed	hub.redeem, test
ingame.push	liveops.execute_action, test
ingame.popup	liveops.execute_action, test
campaign.custom	liveops.execute_action, test

분석 이벤트

analytics.hub.* 및 analytics.checkout.* 집계는 다음 개별 이벤트 유형을 포함합니다:

• analytics.hub.* — analytics.hub.sign_up, analytics.hub.login, analytics.hub.buy_click, analytics.hub.free_item_claimed
• analytics.checkout.* — analytics.checkout.submit_payment_form, analytics.checkout.back_store, analytics.checkout.back_game, analytics.checkout.pageview, analytics.checkout.pageshow, analytics.checkout.pagehide, analytics.checkout.pageexit

Event type	Emitted by
analytics.hub.*	hub.interact, test
analytics.checkout.*	checkout.interact, test

조건부 동작 참고

¹ hub.interact는 쿨다운에 의해 제한되며, 플레이어의 이전 허브 방문 이후 6시간마다 백그라운드 재검증으로 발생합니다. ² hub.login은 로그인 시 스토어를 미리 가져옵니다. ³ hub.store.open은 Store Rules에 verify_player 동작이 포함된 경우에만 player.verify를 발행합니다. ⁴ hub.purchase와 order.captured는 Store 아이템에 세그먼트 규칙이 있는 경우에만 player.verify를 발행합니다. ⁵ s2s.user.authorize와 s2s.player.issue_loyalty_points는 사용자가 새로 생성된 경우에만 player.verify를 발행합니다. 동일한 사용자에 대한 후속 호출은 웹훅을 발행하지 않습니다. ⁶ test는 모든 이벤트 유형에 대해 발생하며, 대시보드의 Send test event를 통해서만 사용할 수 있습니다.

정보

일부 이벤트 유형은 trigger 필드 없이 발행됩니다(예: payment.*, subscription.*, fraud.reported 및 배치 전달 이벤트). 이들은 위 참조에 포함되어 있지 않습니다.

이벤트 유형 및 함수 동작

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

• 플레이어 검증
• 아이템 추가
• 아이템 제거
• 주문 결제 완료 이벤트
• 주문 생성 이벤트
• 주문 취소
• 환불
• 쿠폰 사용됨
• 모바일 푸시
• 게임 내 팝업
• 구독
• 사기 신고됨

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