Webhooks. リアルタイムイベントを、確実にお届けします。

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 にあります。

30 秒以内に HTTP 200（または任意の 2xx ステータスコード）を返してください。レスポンスボディは無視されるため、空のボディや { ok: true } を返して構いません。処理に 30 秒以上かかる場合は、すぐに 200 を返し、イベントを非同期で処理してください（内部キューに入れ、200 を返し、リクエストパス外で処理する）。4xx はリトライに関しては 5xx と同様に扱われ、リトライがトリガーされます。統合に関係のないイベント（例：不要な link.created イベント）を受け取った場合も、不要なリトライを避けるために 200 を返してください。

各 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 リクエスト数も大幅に抑えられます。

個々のイベントペイロードは 10KB 未満です。バッチクリックペイロード（デフォルトモード）は、1 バッチあたり最大 100 イベントで、総ペイロードサイズの上限は 100KB です。バッチが 100KB を超える場合は、自動的に複数の配信に分割されます。クリックの大きなメタデータフィールド（例：長いリファラー URL）は、1 フィールドあたり 2KB で切り捨てられます。レシーバーで厳格なペイロードサイズ制限がある場合は、バッチモードではなく raw-click モード（1 配信につき 1 イベント）を設定してください。

ngrok、Cloudflare Tunnel、localtunnel などのツールを使用して、ローカルサーバーを公開 HTTPS URL で公開し、その URL をテストワークスペースの Webhook エンドポイントとして登録します。あるいは、ダッシュボードの Webhook テスト送信ボタンを使用して、実際のイベントを発生させることなく、登録されたエンドポイントに任意のイベントタイプのサンプルペイロードを送信できます。Elido CLI (elido webhook test --event click.created --endpoint https://...) もスクリプトによるローカルテストに利用できます。

メンテナンス期間中に生成されたイベントは当社のイベントストリームにキューイングされ、メンテナンス終了後に配信されます。Elido のステータスページ (status.elido.app) で計画メンテナンスが事前に告知されます。Webhook 配信 SLA には告知されたメンテナンス期間は含まれません。通常 30〜60 分のメンテナンスであれば、72 時間のリトライウィンドウがあるため、イベントが恒久的に失われることはなく、エンドポイントが再び到達可能になった時点で生成順に配信されます。