주요 콘텐츠로 건너뛰기

Webhook 배치 내보내기

webhook 요청을 통해 이벤트를 직접 전달하는 대신, Aghanim은 일정 시간 창 동안 이벤트를 수집하고 JSONL 파일로 저장한 다음, 배치를 다운로드할 수 있는 사전 서명된 URL과 함께 batch.ready webhook 알림을 전송합니다.

작동 원리

  1. 웹훅을 생성하고 해당 웹훅에서 배치 모드를 활성화합니다.
  2. Aghanim은 일정 시간 창 동안 웹훅의 구독과 일치하는 이벤트를 수집합니다.
  3. 배치가 준비되면 Aghanim은 배치 파일을 다운로드할 수 있는 사전 서명된 URL과 함께 엔드포인트로 단일 batch.ready 알림을 보냅니다.
  4. URL이 만료되기 전(24시간)에 JSONL 파일을 다운로드하고 처리합니다.

배치 모드 활성화

대시보드를 통해

  1. Aghanim 대시보드에서 게임 → 웹훅 → 새 웹훅으로 이동합니다.
  2. 엔드포인트 URL을 입력하고 웹훅 시크릿을 구성합니다.
  3. 배치로 수신할 이벤트 유형을 선택합니다(예: order.created, order.paid).
  4. 배치 모드 옵션을 켭니다.
  5. 웹훅을 저장합니다.

API를 통해

batch_mode 매개 변수를 true로 설정하여 웹훅 생성 API 메서드를 사용합니다.

정보

다음 이벤트에서는 배치 모드를 사용할 수 없습니다:

  • player.verify, player.lookup, store.get — 이러한 이벤트는 서버에서 동기식 응답이 필요하며, 이는 배치 전송과 호환되지 않습니다.
  • item.add, item.remove — 아이템 전달 지연을 방지하기 위해 이러한 이벤트는 배치로 처리하지 않아야 합니다.

배치 알림 처리

배치가 준비되면 Aghanim이 엔드포인트로 batch.ready 알림을 보냅니다. 엔드포인트는 다음을 충족해야 합니다:

  • HTTPS POST 요청을 수락합니다.
  • 요청 서명을 검증합니다.
  • 만료되기 전(24시간)에 제공된 서명된 URL을 사용하여 배치 파일을 다운로드합니다.
  • JSONL 파일을 처리합니다 — 각 줄은 별도의 JSON 이벤트 객체입니다.
  • 성공적으로 처리된 경우에는 2xx 상태 코드로 응답하며, 오류의 경우에는 4xx 또는 5xx를 응답합니다.

알림 스키마

아래는 예시입니다 batch.ready 웹훅 요청:

POST /your/webhook/uri HTTP/1.1
Content-Type: application/json
Host: your-webhook-endpoint.com
User-Agent: Aghanim/0.1.0
X-Aghanim-Signature: 2e45ed4dede5e09506717490655d2f78e96d4261040ef48cc623a780bda38812
X-Aghanim-Signature-Timestamp: 1725548450

{
  "event_type": "batch.ready",
  "event_data": {
    "signed_url": "https://s2s-api.aghanim.com/s2s/v1/batch_export/download?token=eyJhb...NiIs",
    "format": "jsonl",
    "expires_at": 1710786400
  },
  "event_time": 1725548450,
  "event_id": "whevt_eCacGbJVbvToOgzjXUgOCitkQE",
  "idempotency_key": null,
  "request_id": "d1593e9c-c291-4004-8846-6679c2e5810b",
  "sandbox": false,
  "transaction_id": "whtx_eCacGbJVbvT",
  "context": null,
  "game_id": "gm_exTAyxPsVwh"
}

이벤트 스키마

Key유형설명
event_idstringAghanim에 의해 생성된 고유 이벤트 ID.
game_idstringAghanim 시스템에서의 귀하의 게임 ID.
event_typestring이벤트의 유형, batch.ready 이럴 경우.
event_timenumberThe time the event was sent, in Unix epoch time. May differ across duplicate deliveries of the same event.
event_dataEventData이벤트 특정 데이터가 포함되어 있으며, 상속된 객체에 대한 가능한 키가 포함됩니다.
idempotency_keystring|null웹훅 작업이 재시도되어도 한 번만 실행되도록 보장합니다. 일 수 있습니다 null 이벤트 유형에 따라 달라집니다.
request_idstring|null이벤트가 API 요청에 의해 트리거된 경우, 요청 ID가 포함됩니다.
sandboxboolean이 이벤트가 샌드박스 게임 환경에서 전송되었는지를 표시합니다.
triggerstring|null이벤트가 전송된 원인이 된 트리거입니다.
transaction_idstringAghanim이 생성한 거래 ID입니다. 이 ID는 동일한 거래 내에서 발생한 여러 이벤트에서 동일할 수 있습니다.
contextEventContext|null이벤트에 대한 컨텍스트 정보.

EventContext 스키마

Key유형설명
orderOrderContext|null해당되는 경우 이벤트와 관련된 주문 정보입니다.
playerPlayerContext|null플레이어 정보를 추가하려면 웹훅 설정에서 "플레이어 컨텍스트 추가"를 활성화하세요.

EventData 스키마

Key형식설명
signed_url문자열JSONL 파일을 다운로드하기 위한 사전 서명된 URL입니다. 24시간 후에 만료됩니다.
format문자열파일 형식입니다. 항상 jsonl입니다.
expires_atinteger서명된 URL이 만료되는 시점의 Unix 타임스탬프.

배치 파일 형식

각 배치 파일은 JSONL 파일입니다 — 한 줄당 하나의 JSON 이벤트입니다. 각 줄에는 구독한 이벤트 유형과 일치하는 완전한 웹훅 이벤트 객체가 포함됩니다.

예시 파일 내용:

{"event_type":"order.created","event_data":{"id":"ord_eCacpFwavzi","amount":9499,"company_id":"com_exTAxmkZQCO","country":"US","created_at":1725547595,"currency":"USD","game_id":"gm_exTAyxPsVwh","items":[{"id":"itm_exTBZQmIlDz","name":"Crystals","sku":"crystals","quantity":480000,"price":9499,"price_decimal":94.99,"currency":"USD","type":"item","nested_items":null}],"modified_at":1725547657,"player_id":"2D2R-OP3C","receipt_number":"2409051289614565","status":"created","user_id":"usr_eymySUreClx","metadata":null,"creator":null},"event_time":1725547595,"event_id":"whevt_eCacFaIUauSnNfykXTfNChtsjDE","idempotency_key":"idmpt_aXRlb...JkX2VFS","request_id":"c0482e8b-b180-3003-7735-5568b2e4710a","sandbox":false,"trigger":"checkout.purchase","transaction_id":"whtx_eCacFaIUauS","context":null,"game_id":"gm_exTAyxPsVwh"}
{"event_type":"order.paid","event_data":{"id":"ord_eCacpFwavzi","amount":9499,"company_id":"com_exTAxmkZQCO","country":"US","created_at":1725547595,"currency":"USD","game_id":"gm_exTAyxPsVwh","revenue_usd":9099.123,"fees":{"aghanim_fee_usd":10.11,"payment_system_fee_usd":15.123,"taxes_usd":481.198933},"items":[{"id":"itm_exTBZQmIlDz","name":"Crystals","sku":"crystals","quantity":480000,"price":9499,"price_decimal":94.99,"currency":"USD","type":"item","nested_items":null}],"modified_at":1725547657,"player_id":"2D2R-OP3C","receipt_number":"2409051289614565","status":"paid","user_id":"usr_eymySUreClx","metadata":null,"creator":null},"event_time":1725548450,"event_id":"whevt_eCacGbJVbvToOgzjXUgOCitkQE","idempotency_key":"idmpt_aXRlb...JkX2VFS","request_id":"d1593e9c-c291-4004-8846-6679c2e5810b","sandbox":false,"trigger":"checkout.purchase","transaction_id":"whtx_eCacGbJVbvT","context":null,"game_id":"gm_exTAyxPsVwh"}

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

On this page