売上と独自データをLinkHarborに送信する

LinkHarborは外部からのデータも受け付けます。2つのケースには、独自のシークレットを使う専用のエンドポイントがあり、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つ（例：ショップごとに1つ）です。

「編集」

名前を変更し、ステータスを「有効」または「無効」に設定します。無効なシークレットでは、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=と、生の本文のHMAC-SHA256署名（16進数）が入ります。キーはシークレットそのものではなく、その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」と「シークレット」（「シークレットを表示」付き）が表示されます
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アドレスごとに1分あたり120回まで呼び出せます。任意で本文に署名できます。X-LinkHarbor-Signatureヘッダーには、sha256=と、シークレットをキーとした生の本文のHMAC-SHA256署名が入ります。送信する場合は正しい必要があります。