3分で読了機能

リンクイベントのWebhook: ペイロード・署名・再試行

URL短縮サービスのリンクとクリックのWebhook: ペイロード構造、click.created、X-Elido-Signature検証(Node、Python)、再試行、重複排除キー。

Marius Voß
DevRel · edge infra

ElidoのURL短縮サービスのWebhookは、ワークスペースで何かが変わるたびに、署名付きのJSONエンベロープをHTTPSエンドポイントへPOSTします。リンクの作成、編集、削除、有効期限切れ、クリック上限への到達、メンバーの招待、ドメインの検証などです。各リクエストには X-Elido-Signature: v1=<hex> ヘッダーが付きます。これは {timestamp}.{raw_body} に対するHMAC-SHA256で、失敗した配信には約20分の間に3回の試行が行われます。

クリックには専用のイベント click.created があり、独自のルールがあります。プライバシーを抑えたペイロード、エンドポイントごとのレート上限、ボットトラフィックのオプトインです。最後のセクションで扱います。この記事はAPIの外向き側にあたり、内向き側はURL短縮API + SDKクイックスタートで扱っています。リンクイベントの元となる機能の柱はスマートリンクの解説です。

現在Webhookを発火するリンクイベント

以下のイベントは、名前で購読したWebhookエンドポイントに届きます。ダッシュボードの新規エンドポイントフォームには、最もよく使う8つのチェックボックスがあり、APIは一覧にある任意の名前を受け付けます。

イベント発火するタイミングダッシュボードのチェックボックス
link.createdリンクが1件ずつ、または一括インポートで作成されたときあり
link.updated遷移先、設定、ステータスの変更、一括編集、復元あり
link.deletedリンクが単体または一括で削除されたときあり
link.expiredリンクが有効期限を過ぎたときAPIのみ
link.cap_reachedリンクが最大クリック数に達したときAPIのみ
link.brokenリンク切れチェックで遷移先の失敗が検出されたときAPIのみ
click.createdクリックがカウントされたとき(ボットとスキャナーはオプトインしない限りスキップ)あり。ただし初期値ではオフ
workspace.created, workspace.updatedワークスペースが作成されたとき、またはその設定が変わったときあり
member.invited, member.removedメンバーが(直接、SCIM、承諾された招待により)追加または削除されたときあり
member.role_changedメンバーのロールが変わったときAPIのみ
invitation.created, invitation.accepted招待が送信または承諾されたときAPIのみ
domain.verified, domain.ssl_failedカスタムドメインがDNSチェックに合格したとき、または24時間後も失敗するときAPIのみ
audit.event監査ログのエントリがあったときあり

暗号化リンクには、さらに link.encrypted_created と link.encryption_rotated の2つが加わります。リストを手作業で最新に保ちたくない場合は、siem エンドポイントを作成してください。購読フィルターなしで、監査エントリを含むワークスペースのすべてのイベントを受け取れます。

課金イベントも同じキューを通ります。課金サービスは subscription.created、subscription.activated、subscription.paused、subscription.resumed、subscription.frozen、subscription.unfrozen、subscription.change_scheduled、subscription.change_canceled、usage.threshold_80、usage.threshold_100、usage.overage_charged を発行します。siem エンドポイントはこれらも受け取ります。

ロードマップにあり、まだ稼働していないものに、「フォルダーXのリンクのみ」のようなエンドポイント単位のフィルターがあります。それまでは、ハンドラー側で data.slug や data.link_id を見て絞り込んでください。

配信済みのイベント、再試行された配信、ステータスコード 503 で失敗した配信を表示する配信ログつきの Elido の Webhook エンドポイントページ

APIでWebhookエンドポイントを作成する

エンドポイントは1つのワークスペースに属します。/v1/workspaces/{workspace_id}/webhooks へのPOSTで作成します。

curl -X POST "https://api.elido.app/v1/workspaces/$WORKSPACE_ID/webhooks" \
  -H "Authorization: Bearer elido_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/elido",
    "events": ["link.created", "link.updated", "link.deleted"],
    "description": "CRM sync",
    "kind": "event"
  }'

レスポンスは 201 で、エンドポイントと、event と siem の種類については1回限りのシークレットが含まれます。

{
  "endpoint": {
    "id": 7,
    "workspace_id": 42,
    "url": "https://hooks.example.com/elido",
    "events": ["link.created", "link.updated", "link.deleted"],
    "is_active": true,
    "description": "CRM sync",
    "kind": "event",
    "config": {},
    "created_at": "2026-09-21T09:12:44Z"
  },
  "secret": "whsec_9f2c..."
}

シークレットはElidoが生成するため、自分で送る必要はありません。以降の呼び出しでは返されないので、今コピーしてください。kind には6つの値があります。event と siem は、この記事で扱う署名付きJSON配信です。discord、telegram、slack、sentry は、同じイベントをチャットメッセージやSentryイベントの形に整え、URLまたは暗号化されたボットトークンで認証し、HMACヘッダーは付きません。

作成時にはプランが関わります。event のエンドポイントにはPro、Business、Enterpriseのいずれかが必要で、Freeのワークスペースでは 402 Payment Required が返ります(ダッシュボードでは代わりにアップグレードのダイアログが開きます)。siem のエンドポイントにはBusinessかEnterpriseが必要です。チャットとSentryのチャンネルにプランの制限はありません。すでにあるエンドポイントは、ワークスペースがのちにダウングレードしても配信を続けます。

権限については、エンドポイントと配信ログの閲覧には workspace.view が必要です。作成、編集、削除、シークレットのローテーション、配信の再送には workspace.edit が必要で、管理者かオーナーを意味します。APIキーは発行されたワークスペース内で動作し、作成時に選んだロールを超えることはないため、閲覧者レベルのキーで上記のPOSTを行うと 403 になります。詳しいリファレンスはWebhookのドキュメントにあります。

Webhookペイロードのエンベロープ

署名付きの配信はすべて、同じ4フィールドのエンベロープを持ちます。data には変更されたレコードが入るため、リンクイベントではリンクの行になります。

{
  "type": "link.created",
  "workspace_id": 42,
  "data": {
    "id": 91834,
    "workspace_id": 42,
    "domain_id": 3,
    "slug": "spring-sale",
    "destination_url": "https://shop.example.com/spring",
    "title": "Spring sale landing",
    "tags": ["newsletter"],
    "status": "active",
    "expires_at": null,
    "max_clicks": null,
    "redirect_status": 302,
    "created_by_user_id": 17,
    "created_at": "2026-09-21T09:14:02.184311Z"
  },
  "timestamp": "2026-09-21T09:14:02Z"
}

このサンプルは省略したもので、実際の data にはターゲティングルール、フォルダー、キャンペーン、スキャンのフィールドを含むリンクのすべての列が入ります。ボディにはイベントIDも short_url もありません。必要なら、自分のドメインと slug から短縮URLを組み立ててください。スケジュールされたイベントはより小さなオブジェクトを送ります。link.expired には link_id、slug、destination_url があり、link.cap_reached には cap と clicks が加わります。

伏せ字処理の修正前にペイロードをログに記録していた場合に知っておくべき修正が1つあります。シークレットのフィールドは、ペイロードがElidoを出る前に取り除かれるようになりました。パスワード保護リンクの password_hash や招待の token は以前は data に現れていましたが、新しい配信でも配信ログでも、もう現れません。古いペイロードを保存している場合は、そのデータを削除する価値があります。

X-Elido-Signatureヘッダーの検証

署名付きの各リクエストには、次のヘッダーが付きます。

X-Elido-Signature: v1=5d8f0c3e...
X-Webhook-Signature: v1=5d8f0c3e...
X-Webhook-Timestamp: 1790068442
X-Webhook-Event: link.created
X-Webhook-Delivery: 55120
User-Agent: Elido-Webhooks/1.0

2つの署名ヘッダーは同じ値を持ち、X-Webhook-Signature は後方互換のエイリアスです。Elidoは、RFC 2104で定義されたHMAC-SHA256を、whsec_... 文字列全体をキーとして、タイムスタンプ、ドット、生のボディバイトに対して計算します。16進ダイジェストの先頭に v1= が付きます。ヘッダーの中に t= フィールドはなく、タイムスタンプは専用のヘッダーに入っています。

署名検証の流れ: X-Elido-SignatureとX-Webhook-Timestampのヘッダー、生のボディ、シークレットがts、ドット、ボディに対するHMAC-SHA256に入力され、v1=の16進数と定数時間で比較される。その後、受信側の5分間の鮮度チェックで、イベントを処理するか、400で拒否するかに分かれる

Nodeでは、再シリアライズしたオブジェクトではなく、生のバイトに署名します。そのため、Expressではこのルートに express.raw({ type: "application/json" }) が必要です。

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyElido(secret, headers, rawBody, toleranceSec = 300) {
  const ts = headers["x-webhook-timestamp"] ?? "";
  if (!/^\d+$/.test(ts)) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;

  const mac = createHmac("sha256", secret).update(`${ts}.`).update(rawBody);
  const expected = Buffer.from("v1=" + mac.digest("hex"));

  // During a rotation the old secret signs X-Elido-Signature-Previous.
  return ["x-elido-signature", "x-elido-signature-previous"].some((name) => {
    const got = Buffer.from(headers[name] ?? "");
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

長さのチェックは重要です。NodeのtimingSafeEqualは、サイズの異なるバッファに対してfalseを返さず例外を投げます。標準のhmacモジュールを使ったPython版は次のとおりです。

import hashlib
import hmac
import time


def verify_elido(secret: str, headers, raw_body: bytes, tolerance: int = 300) -> bool:
    ts = headers.get("X-Webhook-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
        return False
    digest = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256)
    expected = "v1=" + digest.hexdigest()
    for name in ("X-Elido-Signature", "X-Elido-Signature-Previous"):
        got = headers.get(name)
        if got and hmac.compare_digest(got, expected):
            return True
    return False

検証が失敗し続ける場合は、Webhook署名検証ガイドに、Go版、n8nのCodeノード、不一致のよくある原因があります。5分のウィンドウは、Elido側ではなくあなた側のチェックです。Elidoは再試行を含む各試行に新しいタイムスタンプを付けるため、正当な再試行が古く見えることはありません。このウィンドウがないと、1つのリクエストを捕捉した人が来週それを再生しても、署名は一致してしまいます。

ローテーションは POST /v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secret、またはエンドポイントページのRotateボタンで行います。新しいシークレットは1回だけ得られます。その後の7日間、各配信には旧シークレットで署名された X-Elido-Signature-Previous も付くため、上の両方の関数がそれを試しています。その週のうちにいつ新しいシークレットをデプロイしても、何も失敗しません。

Webhookの再試行ポリシー

配信ワーカーは数秒ごとに保留中の配信を取り出すため、リンクの変更は通常、数秒以内に届きます。2xxの応答があれば配信は完了とされます。2xx以外のステータス、ネットワークエラー、10秒以内に応答がない場合は、試行の失敗として扱われます。

Webhookの再試行スケジュールの棒グラフ: 1回目はT+0、2回目は失敗の5分後のT+5m、3回目はその15分後のT+20m、その後は配信が失敗とマークされ、誰かが「再試行」を押すか再試行エンドポイントを呼ぶまで自動の試行はなし

配信ごとに3回の試行で、全体で20分です。意図的に短くしてあります。正直なところ、不安定なVPNの背後にある受信側なら、私が選ぶよりも短い設定です。こちら側の2時間の障害は、自動再試行ではカバーできません。それをカバーするのが配信ログです。GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries は、各配信をステータス、HTTPコード、レイテンシ、試行回数、次の再試行時刻とともに一覧し、エンドポイントページにも同じ行が「再試行」ボタン付きで表示されます。再試行(または POST .../deliveries/{delivery_id}/retry)は、失敗または配信済みの配信に新しい3回分の試行枠を与え直し、202 を返します。まだ保留中の配信には 409 が返ります。

一部の失敗は再試行されません。chat_id のないTelegramエンドポイントや、不正な形式のSentry DSNは、リクエストを繰り返しても設定の問題は直らないため、すぐに失敗とマークされます。エンドポイントを削除せずにオフラインにするには、"is_active": false を付けて PUT を送ります。一時停止されたエンドポイントには新しい配信が行われません。

ハンドラーが重い処理を行う場合は、先に 200 を返してからジョブをキューに入れてください。10秒の打ち切りは、遅いが成功しているハンドラーが重複に変わる境目であり、これが重複排除の話につながります。

チーム向けに受信側を計画していますか。Webhook機能ページに、これらすべてのダッシュボード側が示されています。

Webhookの冪等性と順序

Elidoは少なくとも1回は配信します。再試行のセクションでは、重複が起きる1つの経緯を示しました。ハンドラーが処理をコミットしたものの、10秒のウィンドウに間に合わず、Elidoが再送するケースです。手動の再試行は、意図的な再送です。

どちらの場合も X-Webhook-Delivery の値は同じままです。これは1回の試行ではなく、1つのエンドポイントへの1回の配信のIDだからです。これをキーにします。

CREATE TABLE elido_webhook_seen (
  delivery_id BIGINT PRIMARY KEY,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- in the handler, inside the same transaction as your work:
INSERT INTO elido_webhook_seen (delivery_id) VALUES ($1)
ON CONFLICT (delivery_id) DO NOTHING
RETURNING delivery_id;
-- no row back means you've already handled this delivery

同じイベントを購読する2つのエンドポイントには異なる配信IDが付くため、エンドポイントごとに重複を排除してください。当方側でまれに再起動が起きたとき、イベントが別々の配信として2回キューに入ることがあります。二重書き込みが問題になる場合は、type と data.id と data.updated_at による2つ目のガードを追加してください。

順序の保証はありません。配信は期限の古いものから順に送り出されますが、早いイベントの再試行が、後のイベントより後に届くことがあります。リンクを上書きする前に、data.updated_at を保存済みの値と比較してください。エンベロープの timestamp は秒単位の精度しかないため、順序付けには頼らないでください。

click.created Webhook

click.created は、カウントされたクリックごとに署名付きの配信を1件送ります。リダイレクト経路上にはありません。リダイレクトはクリックを発行して先へ進み、これはファイア・アンド・フォーゲットのクリック取り込みの記事で説明しているとおりで、イベントは後から、保存されたクリックから組み立てられます。クリックからPOSTまでは、ミリ秒ではなく数秒かかると考えてください。

data オブジェクトは次のようになります。

{
  "type": "click.created",
  "workspace_id": 42,
  "timestamp": "2026-11-12T10:04:31Z",
  "data": {
    "id": "clk_3_99120",
    "link_id": 9183,
    "workspace_id": 42,
    "slug": "spring",
    "host": "go.acme.example",
    "short_url": "https://go.acme.example/spring",
    "timestamp": "2026-11-12T10:04:29Z",
    "country": "DE",
    "device": "mobile",
    "browser": "Safari",
    "referer_host": "news.ycombinator.com",
    "ip": "203.0.113.0",
    "is_bot": false,
    "is_scanner": false
  }
}

届く内容は、いくつかのルールで決まります。

  • プライバシー優先。ペイロードは、ワークスペースの分析プライバシー設定を適用した後で組み立てられます。IPは常に短縮したネットワーク部分(IPv4は/24、IPv6は/48)だけで、個人データなしモードでは完全に除外されます。リファラーはホストまでに切り詰められ、パスやクエリ文字列は外に出ません。
  • ボットは初期設定でオフ。is_bot または is_scanner が付いたクリック(リンクを先読みするメールのセキュリティスキャナーなど)は、エンドポイントで「ボットとスキャナーのクリックを含める」にチェックを入れるか、API経由で config.include_bot_clicks: true を送らない限りスキップされます。既知のクローラーやリンクプレビューのボットはクリックとして数えられないため、送信されません。
  • キューではなくレート上限。各エンドポイントには1秒あたり最大50件のクリックイベントが割り当てられます。超過分は遅延ではなく破棄されるため、バイラルになったリンクでも受信側が埋もれることはありませんが、ピーク時にはWebhookが完全な台帳ではないことも意味します。すべてのクリックが重要なら、分析APIと突き合わせてください。
  • data.id で重複排除。配信は他のイベントと同じく少なくとも1回です。クリックが2回処理されても data.id は変わらず、X-Webhook-Delivery は1回の配信の再試行をカバーします。
  • 再試行と署名は同じ。3回の試行(即時、5分後、15分後)と、この記事の前半で見た X-Elido-Signature の検証です。

click.created を受け取るのは、チェックを入れた event エンドポイントだけです。ダッシュボードのフォームにはこれが一覧されますが、あらかじめチェックが入ることはなく、Discord、Telegram、Sentry、siem のエンドポイントには届きません。Zapier(Webhooks by ZapierのCatch Hook)、Make(Custom webhook)、n8n(Webhookノード)は、いずれもこれをトリガーとして受け取れます。

クリックデータには、ほかにも2つの経路が今も有効です。イベントフォワーダーは、各クリックをすでに使っているツールのサーバー側イベントにします。Mixpanelのリンククリックイベント、Klaviyoのクリックイベントをプロファイルへ、運用ダッシュボード向けのDatadogのリダイレクトメトリクスがあります。そして分析API、つまり GET /v1/analytics/workspaces/{workspace_id}/clicks/recent と clicks.csv のエクスポートが、完全な記録です。どちらが合うかはクリック追跡におけるWebhookとポーリングの比較で解説しています。

柱となる記事はこちらです: スマートリンクの解説。

ブログの関連記事

よくある質問

Elidoはリンクのクリックごとにwebhookを送信しますか?

はい。click.createdイベントを使います。カウントされたクリックごとに、発生の数秒後に署名付きの配信が1件届きます。ボットやセキュリティスキャナーのクリックは、エンドポイントが明示的にオプトインしない限りスキップされ、各エンドポイントは1秒あたり50件のクリックイベントが上限で、超過分はキューに積まれずに破棄されます。バイラルになったリンクの完全な記録が必要な場合は、分析APIも併せて読み取ってください。

ElidoのWebhook署名はどう検証しますか?

X-Webhook-Timestampの値、ドット、生のリクエストボディに対し、whsec_で始まるシークレットをキーとしてHMAC-SHA256を計算します。16進数にエンコードして先頭にv1=を付け、X-Elido-Signatureヘッダーと定数時間で比較します。5分より古いタイムスタンプは拒否してください。

Elidoは失敗したWebhookを何回再試行しますか?

各配信には3回の試行があります。即時に1回、失敗の5分後に1回、その15分後にもう1回です。2xx以外のステータス、ネットワークエラー、10秒より遅い応答はいずれも失敗として扱われます。3回目の後は、「再試行」を押すまで配信は失敗としてマークされます。

X-Elido-SignatureとX-Webhook-Signatureの違いは何ですか?

名前以外に違いはありません。どちらのヘッダーにも同じv1=署名が入ります。X-Elido-Signatureが主で、X-Webhook-Signatureは後方互換のエイリアスとして残されているため、新しいコードでは前者を使ってください。シークレットのローテーション中は、ElidoはX-Elido-Signature-Previousも送信します。これは旧シークレットで署名され、7日間送られます。

同じWebhookを二重に処理しないようにするにはどうすればよいですか?

X-Webhook-Deliveryヘッダーの値を保存し、すでに処理した値のリクエストはスキップします。この値は1つのエンドポイントへの1回の配信を識別し、自動再試行や手動の再送でも変わらないため、この値に一意インデックスを張れば十分です。

ワークスペースでWebhookを作成または削除できるのは誰ですか?

ワークスペースの管理者とオーナーです。エンドポイントの一覧表示と配信ログの閲覧には閲覧権限が必要で、作成、編集、削除、シークレットのローテーション、配信の再送にはworkspace.edit権限が必要です。APIキーは、キー作成時に選んだロールが上限になります。

Elidoを試す

URLを貼り付けて短縮リンクを取得

登録不要。リンクは30日間有効。永久に保存するには登録してください。

無料アカウントが必要です。無料プランには合計 25 件のリンクが含まれます。 アカウントをお持ちですか? ログイン

Elidoを試す

EUホスティングのURL短縮サービス。カスタムドメイン、詳細な分析、オープンAPI付き。無料プラン - クレジットカード不要。

タグ
url shortener webhooks
link click webhook
webhook signature verification
webhook retry policy
webhook idempotency
webhook payload

続きを読む