판매와 사용자 지정 데이터 보내기

LinkHarbor는 외부에서 오는 데이터도 받습니다. 두 가지 경우에는 자체 시크릿이 있는 전용 엔드포인트가 있으며, API 키가 필요 없습니다. 판매 콜백은 쇼핑몰의 판매를 보고하므로 통계에서 어떤 링크가 매출을 가져왔는지 볼 수 있습니다. “Custom (API)” 연동은 자체 도구의 라이브 데이터를 위젯으로 페이지에 보여 주고 푸시 알림을 보낼 수 있습니다.

#판매 콜백: 판매 연결하기

클릭 ID(lt_click_id), 연결, 보고가 어떻게 맞물리는지는 전환과 판매 귀속에서 설명하며, 여기에는 개발자를 위한 모든 필드와 응답이 있습니다. 요약하면, LinkHarbor가 집계된 클릭을 http 또는 https 대상으로 리디렉션할 때 lt_click_id 파라미터를 붙이고, 쇼핑몰은 이를 기억했다가 구매 후 다시 보냅니다.

콜백 시크릿 만들기

1. “콜백 및 API”를 엽니다
2. “콜백 시크릿” 카드에서 “+ 새 시크릿 만들기”를 클릭합니다
3. 필요하면 이름을 붙이고(예: “쇼핑몰 콜백”) “시크릿 만들기”를 클릭합니다
4. 시크릿은 한 번만 표시되므로 바로 복사합니다

누가

Creator Pro부터 소유자와 관리자가 만들 수 있습니다. Creator Free에서는 “콜백 시크릿은 Creator Pro부터 사용할 수 있습니다.”가 표시됩니다.

몇 개

워크스페이스당 최대 5개입니다. 예를 들어 쇼핑몰마다 하나씩 만듭니다.

“편집”

이름을 바꾸고 상태를 “활성” 또는 “비활성”으로 설정합니다. 비활성 시크릿이면 API가 콜백을 거부합니다.

“↺ 교체”

새 시크릿을 만듭니다. 이전 시크릿은 즉시 작동을 멈춥니다.

“마지막 콜백:”

시크릿이 마지막으로 성공적으로 사용된 시점을 보여 줍니다.

콜백 보내기

curl -X POST https://dock.at-harbor.com/v1/callbacks/sale \
  -H "Content-Type: application/json" \
  -H "X-Callback-Secret: $LH_CALLBACK_SECRET" \
  -d '{
    "click_id": "3f1c2a9e-8d4b-4a51-9f0e-6b7c1d2e3f40",
    "order_id": "A-10023",
    "amount": "49.90",
    "currency": "EUR",
    "occurred_at": "2026-11-01T10:15:00Z"
  }'
# → {"ok":true,"conversion_id":123}

선택형 서명

시크릿 외에 X-Callback-Signature 헤더를 보낼 수 있습니다. 여기에는 sha256=와 원본 본문의 16진수 HMAC-SHA256 서명이 들어갑니다. 키는 시크릿 자체가 아니라 바이너리 형태의 SHA-256 해시입니다. 헤더를 보낸다면 반드시 올바라야 하며, 그렇지 않으면 콜백이 거부됩니다.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // 시크릿의 바이너리 해시
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// 헤더: X-Callback-Secret과 X-Callback-Signature: $sig, 본문: $body

판매를 보는 곳

보고된 판매는 통계에 전환으로 나타납니다. 전환과 판매 귀속을 참고하세요. API에서는 read:stats로 /v1/stats/…/conversions/breakdown에서 읽습니다.

#Custom (API): 자체 라이브 데이터

“Custom (API)” 연동을 쓰면 게임 서버 플러그인, 봇, cron 스크립트처럼 HTTP 요청을 보낼 수 있는 모든 프로그램이 LinkHarbor로 데이터를 보낼 수 있습니다. 데이터는 페이지의 라이브 위젯이 되고, 푸시 규칙으로 팔로워에게 알릴 수 있습니다.

연결하기

1. 워크스페이스에서 “연동”을 엽니다
2. “Custom (API)”를 고르고 이름을 입력합니다
3. 연결되면 대화상자에 “Ingest URL”과 “Secret”(“Secret 표시”로 보기)이 표시됩니다
4. 둘 다 도구에 저장합니다

연동은 Creator Pro부터 쓸 수 있습니다. Ingest URL과 시크릿은 나중에 연동 상세 보기에서도 소유자와 관리자만 볼 수 있습니다. 연결을 해제하고 다시 연결하면 새 시크릿이 만들어집니다. 연동을 연결하는 일반적인 방법은 연동 연결하기에서 설명합니다.

데이터 보내기

curl -X POST "$INGEST_URL" \
  -H "Authorization: Bearer $INGEST_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "player.joined",
    "event_id": "join-2026-11-01T20:01:02Z-steve",
    "data": { "player": "Steve" },
    "state": {
      "type": "game_server",
      "name": "Survival SMP",
      "online": true,
      "players_online": 3,
      "players_max": 20
    }
  }'
# → {"ok":true,"event_id":4711,"duplicate":false,"event_type":"player.joined"}

event

자유롭게 정하는 이벤트 이름입니다. 예: player.joined. 소문자로 변환되며 푸시 규칙이 반응하는 이름입니다. event가 없으면 이벤트 이름은 state.updated입니다.

event_id

중복 처리를 막는 선택형 키입니다. 같은 event_id를 다시 보내면 LinkHarbor가 duplicate: true로 응답하고 아무것도 하지 않습니다.

data

푸시 텍스트의 플레이스홀더(예: {player})에 들어갈 값입니다. 키 최대 40개, 단순한 값만 가능합니다.

state

위젯의 전체 상태입니다. 이전 상태를 완전히 대체합니다. type은 game_server(게임 서버 카드) 또는 status(상태 카드)입니다.

Authorization: Bearer 대신 X-LinkHarbor-Secret 헤더로 시크릿을 보낼 수도 있습니다. IP 주소당 분당 120회까지 허용됩니다. 원하면 본문에 서명할 수 있습니다. X-LinkHarbor-Signature 헤더에 sha256=와 시크릿을 키로 한 원본 본문의 HMAC-SHA256 서명을 넣습니다. 보낸다면 반드시 올바라야 합니다.