Webhooks. Real-time events, delivered reliably.
ワークスペースごとの Webhooks エンドポイントで、クリック、コンバージョン、リンク管理イベントを HMAC-SHA256 署名付きで受信します。指数バックオフによる自動リトライ機能を搭載。SIEM モードにより、セキュリティプラットフォームへのイベントストリーミングも可能です。
- 10+ event types — clicks, conversions, domain changes
- HMAC-SHA256 signature on every delivery
- 72-hour exponential-backoff retry
- Delivery log with one-click replay
Event types
10+ event types out of the box
Subscribe per endpoint — receive only the events you care about. High-volume click events ship in a 5-second batched window by default; raw-click mode delivers per-click for stream processors.
- link.clicked
Every redirect click. Batched (5s window) or raw-click mode.
- link.created
A new short link was created in the workspace.
- link.updated
Link metadata, target URL, or rules changed.
- link.deleted
Link removed — update any downstream references.
- domain.verified
Custom domain passed DNS verification.
- conversion.attributed
Revenue event matched to a click via Stripe or Shopify.
- campaign.completed
Campaign reached its end date or click cap.
- member.invited
Workspace member added or SCIM-provisioned.
Plus link.expired, link.click_cap_reached, domain.ssl_issued, and more — see the full event catalog.
Delivery guarantees
Exponential backoff. 72-hour window.
A non-2xx response or a 30-second timeout triggers automatic retries: 30 s → 2 min → 10 min → 30 min → 2 h → 8 h → 24 h → 48 h. After 72 hours the delivery is permanently failed and removed from the queue — but still in the delivery log for manual replay.
- 30-second response timeoutReturn 200 immediately; process async if your handler is slow.
- 8 retry attempts over 72 hoursExponential backoff — no avalanche effect on restart.
- Auto-pause after 30 consecutive failuresWorkspace admin notified by email. Resume from dashboard.
- One-click replay from logOriginal payload, same event_id — receiver must be idempotent.
| Event | Endpoint | Status | Latency | Time | |
|---|---|---|---|---|---|
link.clicked | api.acme.com/wh | 200 | 142ms | 14:04:31 | |
link.created | api.acme.com/wh | 200 | 88ms | 14:03:19 | |
conversion.attributed | logs.acme.com | 500 | 30001ms | 14:02:01 | |
domain.verified | api.acme.com/wh | 200 | 67ms | 13:58:44 | |
link.deleted | logs.acme.com | timeout | 30000ms | 13:55:12 |
Delivery log
Full log. Filter, inspect, replay.
Every attempt is logged: event ID, event type, endpoint URL, HTTP status, response body (up to 4 KB), and latency. Retention is 30 days on Pro, 90 days on Business.
- Filter by event type, endpoint, status, and date range
- Failed entries show full request body for debugging
- Replay sends original payload — same event_id
- API: POST /v1/webhooks/deliveries/:id/replay
- SIEM mode: structured JSON with 7-day retry guarantee
What you can do
- クリック、コンバージョン、リンク、ドメインイベント
- HMAC-SHA256 によるリクエスト署名
- 最大72時間の自動リトライ
- セキュリティイベント転送用の SIEM モード
- イベントタイプ別のトピックフィルタリング
- リプレイ機能付きの Webhook 配信ログ
Elido Webhooks の配信内容と仕組み
Webhooks の価値はその信頼性にあります。以下のセクションでは、配信保証、署名検証、リトライ動作、および SIEM モードについて説明します。
クリック、コンバージョン、リンクライフサイクル、ドメインイベントをエンドポイントごとに設定可能
各 Webhook エンドポイントは、click.created（すべてのリダイレクトクリック）、conversion.created（Stripe、Shopify、またはカスタムエンドポイントからのコンバージョンイベント）、link.created、link.updated、link.deleted、link.expired、link.click_cap_reached、domain.verified、domain.ssl_issued、domain.ssl_error、workspace.member.added、workspace.member.removed などのイベントタイプを購読できます。大量のクリックイベントはノイズになる可能性があるため、デフォルトでは click.created は 5 秒の集計ウィンドウ（最大 100 イベントのバッチ配信）で送信されます。リアルタイム配信が必要な場合は、エンドポイントで raw-click モードを有効にしてください。ただし、このモードでは高トラフィックのワークスペースで毎分数千のリクエストが発生する可能性があるため、スループットを処理できるエンドポイントでのみ有効にする必要があります。
すべてのリクエストは HMAC-SHA256 で署名されています。処理前に X-Elido-Signature ヘッダーを検証してください。
Elido は、エンドポイントに設定された共有シークレットを使用して、すべての Webhook リクエストボディを HMAC-SHA256 で署名します。署名は 'sha256=<hex_digest>' として X-Elido-Signature ヘッダーに含まれます。検証方法：共有シークレットを使用して生のリクエストボディに対して HMAC-SHA256 を計算し、タイミング攻撃を防ぐために定数時間比較関数を使用して結果をヘッダー値と比較します。署名を検証する前に Webhook ペイロードを処理しないでください。シークレットはエンドポイント作成時に一度だけ表示されます。ダッシュボードでローテーションでき、ゼロダウンタイムのオーバーラップ期間（新しいシークレットの生成後 15 分間は古いシークレットも有効）が設けられています。Node.js、Python、Go での署名検証のコード例は、/docs/guides/webhooks の Webhooks ガイドにあります。
指数バックオフによる自動リトライ — 配信失敗とマークされるまで最大 72 時間
エンドポイントが 2xx 以外のステータスコードを返したり、タイムアウト（30 秒のレスポンスタイムアウト）が発生したりした場合、Elido は指数バックオフ（30 秒、2 分、10 分、30 分、2 時間、8 時間、24 時間、48 時間）で配信をリトライします。72 時間のウィンドウを過ぎると、配信は恒久的に失敗したとマークされ、リトライキューから削除されます。失敗した配信は、最終的な HTTP ステータスコード（または 'timeout'）とともに Webhook 配信ログに表示されます。ダッシュボードまたは API (POST /v1/webhooks/deliveries/:id/replay) から失敗した配信をリプレイできます。これはダウンストリームの障害後にイベントバッチを回復するのに便利です。30 回連続で 5xx を返したエンドポイントは自動的に一時停止され、ワークスペース管理者にメールで通知されます。根本的な問題が解決したら、ダッシュボードからエンドポイントを再開してください。
SIEM モードはワークスペースの監査イベントを Splunk、Datadog、または任意の HTTPS ログ収集エンドポイントにストリーミングします
SIEM モードは、セキュリティイベント転送のための特別な Webhook 設定です。アプリケーションイベント（クリック、コンバージョン）の代わりに、SIEM モードはワークスペースの監査イベント（SSO ログイン、ログイン失敗、API キーの作成/ローテーション/削除、SCIM プロビジョニングイベント、ロールの変更、Webhook シークレットのローテーション、管理者アクション（リンクの削除、一括エクスポート））を配信します。ペイロード形式は、主要な SIEM プラットフォームへの取り込み用に設計された標準スキーマ（タイムスタンプ、アクター、アクション、ターゲット、workspace_id、ip_address、user_agent）を持つ構造化 JSON です。SIEM Webhooks は最大 7 日間のリトライで配信が保証され、アプリケーション Webhooks とは別に署名されます。検証済みの統合先：Splunk HTTP Event Collector (HEC)、Datadog Logs API、Elastic Logstash HTTP 入力、および一般的な HTTPS ログエンドポイント。SIEM モードは Business プラン専用の機能です。
リクエストボディ、レスポンスコード、失敗した配信のワンクリックリプレイを含む完全な配信ログ
すべての Webhook 配信試行が記録されます：イベント ID、イベントタイプ、エンドポイント URL、配信タイムスタンプ、HTTP ステータスコード、レスポンスボディ（最大 4KB）、レイテンシ。配信ログは、イベントタイプ、エンドポイント、日付範囲、ステータス（配信済み、リトライ中、失敗）で照会可能です。失敗した配信には完全なリクエストボディが含まれているため、リプレイせずに対象のイベントを検査できます。リプレイ：POST /v1/webhooks/deliveries/:id/replay は、元のペイロード（新しいイベントではない）をエンドポイントに送信します。受信側でのべき等性の確保が必要です。配信ログの保持期間は Pro で 30 日、Business で 90 日です。Webhook イベントの永続的な監査については、SIEM エンドポイントを設定するか、監査ログのスケジュールエクスポートを有効にしてください。
Elido Webhooks を本番環境で使用しているエンジニアリングチーム
名前はプレースホルダーです。実際のカスタマーケーススタディが公開され次第、ここに掲載されます。
“独自の分析パイプラインにデータを取り込むために、バッチモードで click.created Webhooks を利用しています。HMAC 署名の検証とリプレイ機能付きの配信ログのおかげで、部分的な障害のデバッグ時間を大幅に短縮できました。ソースからイベントを再構築することなく、ダッシュボードから失敗したイベントバッチをリプレイできました。”
“ワークスペースの監査イベントを Splunk HEC にストリーミングする SIEM モードは、当社の情報セキュリティチームが必要としていたエンタープライズ機能でした。SSO ログインイベントや API キーのローテーションを適切なスキーマで Splunk に取り込めたことで、導入から 1 日以内に Elido のアクセスイベントを SIEM のアラートルールに関連付けることができました。”
“link.expired Webhooks を利用して、印刷物のデータベースを更新する社内ワークフローをトリガーしています。QR コードのリンクが期限切れになると、運用チームに物理ラベルを更新するタスクが自動的に割り当てられます。リンクの期限切れ状態を手動で監視する必要は一切ありません。”
Elido Webhooks vs Bitly vs Short.io
Bitly も Short.io も、HMAC 署名とリトライ保証を備えたアウトバウンド Webhooks を提供していません。この比較では、その差を率直に示しています。
| Feature | Elido | Bitly | Short.io |
|---|---|---|---|
| アウトバウンド Webhooks | あり — ワークスペースごとのエンドポイント、イベントタイプ別の購読 | 利用不可 | あり — クリック時の基本的な Webhook |
| HMAC-SHA256 署名 | あり — すべての配信に署名、コード例を提供 | 該当なし | 一部あり — 署名ヘッダーは存在するがドキュメントなし |
| 自動リトライ | あり — 指数バックオフ、72 時間のウィンドウ | 該当なし | なし — 送信のみ（Fire and Forget） |
| リプレイ機能付き配信ログ | あり — Pro は 30 日、Business は 90 日、ワンクリックリプレイ | 該当なし | なし |
| SIEM 監査イベントモード | あり — Business 限定、SIEM 取り込み用の構造化 JSON | 利用不可 | 利用不可 |
| 失敗時のエンドポイント自動一時停止 | あり — 30 回連続失敗で停止、管理者に通知 | 該当なし | 利用不可 |
| イベントタイプ | クリック、コンバージョン、リンクライフサイクル、ドメイン、監査イベント | 該当なし | クリックのみ |
Webhook に関する質問
HMAC-SHA256 署名を検証するにはどうすればよいですか？
JSON パース前の生のリクエストボディをバイト列として読み取り、エンドポイントの共有シークレットを使用してそのバイト列に対して HMAC-SHA256 を計算します。結果を 16 進数（hex）エンコードし、'sha256=' プレフィックスを除いた X-Elido-Signature ヘッダーの値と比較します。タイミング攻撃を防ぐために、定数時間比較関数（例：Python の hmac.compare_digest、Node.js の crypto.timingSafeEqual）を使用してください。標準的な文字列比較演算子で署名を比較しないでください。Node.js、Python、Go のコード例は /docs/guides/webhooks#verification にあります。
Webhook レシーバーは何を返すべきですか？
30 秒以内に HTTP 200（または任意の 2xx ステータスコード）を返してください。レスポンスボディは無視されるため、空のボディや { ok: true } を返して構いません。処理に 30 秒以上かかる場合は、すぐに 200 を返し、イベントを非同期で処理してください（内部キューに入れ、200 を返し、リクエストパス外で処理する）。4xx はリトライに関しては 5xx と同様に扱われ、リトライがトリガーされます。統合に関係のないイベント（例：不要な link.created イベント）を受け取った場合も、不要なリトライを避けるために 200 を返してください。
Webhook イベントのべき等性はどのように機能しますか？
各 Webhook ペイロードには event_id フィールド（UUID）が含まれています。これをレシーバー側のべき等キーとして使用してください。部分的な障害によるリトライなどで同じ event_id を 2 回受信した場合は、1 回だけ処理するようにします。受信したイベント ID は、少なくとも 72 時間（リトライウィンドウ）の TTL を持つ重複排除テーブルに保存してください。リトライのペイロードはオリジナルと同一（同じ event_id、同じボディ）であるため、「この event_id を以前に見たか？」という単純なチェックで十分です。
エンドポイントが自動的に一時停止されるのはなぜですか？
30 回連続で配信に失敗（2xx 以外またはタイムアウト）すると、エンドポイントは自動的に一時停止されます。これは、Elido が壊れたエンドポイントを無期限に攻撃し続けるのを防ぐためです。根本的な原因（URL の変更、サーバーのダウン、処理の遅延による 30 秒のタイムアウトなど）を修正してから、ダッシュボードでエンドポイントを再開してください。再開しても、一時停止中にスキップされたイベントは自動的にリプレイされません。それらのイベントを回復する必要がある場合は、配信ログから手動でリプレイしてください。
すべてのクリックに対してリアルタイムでクリックイベントを受信できますか？
はい。エンドポイントで raw-click モードを有効にしてください。このモードでは、Elido はクリックから 2 秒以内に click.created イベントをバッチ処理なしで個別に配信します。高トラフィックのワークスペースでは raw-click モードにより毎分数千のイベントが発生する可能性があるため、レシーバーがそのスループットを処理できることを確認してください。ほとんどの分析用途では、デフォルトの 5 秒間のバッチ集計（1 ペイロードあたり最大 100 クリック）で十分であり、HTTP リクエスト数も大幅に抑えられます。
Webhook イベントのペイロードサイズの制限は？
個々のイベントペイロードは 10KB 未満です。バッチクリックペイロード（デフォルトモード）は、1 バッチあたり最大 100 イベントで、総ペイロードサイズの上限は 100KB です。バッチが 100KB を超える場合は、自動的に複数の配信に分割されます。クリックの大きなメタデータフィールド（例：長いリファラー URL）は、1 フィールドあたり 2KB で切り捨てられます。レシーバーで厳格なペイロードサイズ制限がある場合は、バッチモードではなく raw-click モード（1 配信につき 1 イベント）を設定してください。
開発中にローカルで Webhooks をテストする方法はありますか？
ngrok、Cloudflare Tunnel、localtunnel などのツールを使用して、ローカルサーバーを公開 HTTPS URL で公開し、その URL をテストワークスペースの Webhook エンドポイントとして登録します。あるいは、ダッシュボードの Webhook テスト送信ボタンを使用して、実際のイベントを発生させることなく、登録されたエンドポイントに任意のイベントタイプのサンプルペイロードを送信できます。Elido CLI (elido webhook test --event click.created --endpoint https://...) もスクリプトによるローカルテストに利用できます。
計画メンテナンス中に Webhook イベントはどうなりますか？
メンテナンス期間中に生成されたイベントは Redpanda にキューイングされ、メンテナンス終了後に配信されます。Elido のステータスページ (status.elido.app) で計画メンテナンスが事前に告知されます。Webhook 配信 SLA には告知されたメンテナンス期間は含まれません。通常 30〜60 分のメンテナンスであれば、72 時間のリトライウィンドウがあるため、イベントが恒久的に失われることはなく、エンドポイントが再び到達可能になった時点で生成順に配信されます。