Webhooks: リンクとクリックのイベントを購読する

Webhookは、イベントが発生した時点でElidoからサーバーにイベントをプッシュします。リアルタイムデータが必要な場合はAPIのポーリングの代わりに使用してください — 一般的なユースケースには、リンクのメタデータをCRMに同期する、カスタムダッシュボードを構築する、またはリンクが公開されたときにCIパイプラインを起動するなどがあります。

Webhookエンドポイントの追加#

Dashboard → Webhooks → New endpoint。
POSTを送信する先のURLを貼り付けます。HTTPSである必要があります — 作成時にプレーンHTTPは拒否されます。
必要なイベントの種類を選択します。完全なリストは以下のとおりです。
（オプション）Signing secretを貼り付けるか、自動生成させてください。Secretは一度だけ表示されます。ページを離れる前にコピーしてください。
Save。エンドポイントが到達可能かどうかを確認できるよう、すぐにテストイベントを送信します。

イベントカタログ#

現在のイベントの種類です。名前は <resource>.<action> の形式に従い、バージョン間で安定しています。

link.created — 新しい短縮リンクが作成されました。
link.updated — 宛先URL、スラグ、有効期限、またはパスワードが変更されました。
link.deleted — リンクがソフト削除されました（30日間は回復可能）。
link.clicked.aggregated — 60秒ごとに、前の時間窓のリンクごとのクリック数を送信します。Webhookでクリックごとのイベントは配信しません（ほとんどのエンドポイントが処理しきれないため）— 生のイベントデータにはクリックエクスポートを使用してください。
domain.verified — カスタムドメインのDNS確認が合格しました。
domain.tls_renewed — CaddyがカスタムドメインのTLS証明書を更新しました。
qr.generated — QRコードのSVG/PNGがレンダリングされました。
abuse.flagged — URLスキャナーが宛先を不審なものとしてマークしました。
member.invited / member.removed — ワークスペースメンバーシップの変更。

ペイロードの構造#

すべてのイベントは同じエンベロープを持ちます：

{
  "id": "evt_2c8L9N4M5",
  "type": "link.created",
  "created_at": "2026-05-15T09:42:11.382Z",
  "workspace_id": 4123,
  "data": {
    "link_id": 891234,
    "slug": "spring-2026",
    "destination": "https://acme.com/spring-sale",
    "created_by": "user_5821"
  }
}

id は配信ごとに一意です。べき等性のために使用してください — 同じ id を2回受け取った場合（再試行のため）、重複をスキップしてください。

署名の検証#

エンドポイントのsecretを使ってHMAC-SHA256で各Webhookボディに署名します。署名は t=<unix_ts>,v1=<hex> の形式で Elido-Signature ヘッダーに含まれます。

Nodeでの検証方法：

import { createHmac } from "node:crypto";

function verify(secret: string, body: string, header: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=")),
  );
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${body}`)
    .digest("hex");
  return expected === parts.v1;
}

リプレイ攻撃を防ぐため、署名済みペイロードにタイムスタンプを含めています。|now - t| > 300 秒のイベントは拒否してください。

再試行#

失敗した配信（2xx以外の応答、または10秒以内に応答なし）は指数バックオフで再試行します：30秒、1分、5分、30分、2時間、12時間。6回の失敗後、エンドポイントを failing としてマークし、その特定のイベントの再試行を停止します。エンドポイントはサブスクライブしたままです。新しいイベントは引き続き配信を試みます。

エンドポイントが5回連続で failing の場合 → 自動的に無効化し、ワークスペースオーナーにメールを送信します。サーバーを修正した後、ダッシュボードで再度有効にしてください。

配信ログ#

ダッシュボードで任意のWebhookを開くと、最新500件の配信履歴（各配信のステータスコード、応答時間、リクエスト/レスポンスボディ）を確認できます。失敗した配信はこのビューから手動で再送できます。

ローカルテスト#

Elido CLIを使用してWebhookをlocalhostに転送します：

npx @elido/cli webhooks forward --url http://localhost:3000/webhooks

CLIはCtrl-Cまで続く一時的なエンドポイントを登録し、配信をローカルマシンにトンネリングして、各イベントのリクエストボディを表示します。

制限事項#

ワークスペースあたり20エンドポイント（Pro）、100（Business）。
署名済みペイロードの最大サイズは10 KB。大きなペイロードは分割されます — data には truncated: true フラグと完全なボディを取得するURLが含まれます。
エンドポイントあたり毎秒50イベントの持続レート。バーストはキューに入れられます。

トラブルシューティング#

配信ログでエンドポイントが401を報告している。 エンドポイントが間違ったsecretで署名を検証しています。Webhooks → Endpoint → Settings のsecretとサーバーに保存されているsecretを比較してください。

一部のイベントが2回届く。 応答が遅かったため再試行したか、エンドポイントが応答せずにタイムアウトした可能性があります。べき等性のためにイベントの id を使用してください。

link.clicked.aggregated のカウントがアナリティクスダッシュボードと一致しない。 ダッシュボードはリアルタイム（クリックから30秒以内）ですが、Webhookは60秒の窓があります。また、ダッシュボードでフィルタリングされたボットがボットフィルター窓が閉じるまで生の集計に含まれるため、小さな（約1%の）差異もあります。