Pipedriveのリンククリック追跡：ショートリンクのヒットからディールを作成する

Elido の Pipedrive リンククリック追跡は、ショートリンクのマイルストーンをパイプラインイベントに変換します。リンクが 100、1,000、10,000 クリックを超えると、5 分ごとの cron が指定した Pipedrive パイプラインとステージにディールを作成します。ディールにはリンクのスラッグ、UTM ソース、そして Elido へのディープリンクが notes に含まれます。Zapier は不要で、手動エクスポートも、リンクレポートを確認するためのカレンダーリマインダーも必要ありません。

これが概要です。ただし、仕組みのほうが重要なので、この記事では営業オペレーションチームが有効化する前に把握しておくべき 3 つの事項を説明します。1 つ目は、Connect フローの実際の動作として、個人 API トークンの保管場所、パイプラインピッカーが読み取る内容、トークンを貼り付けた後の保存方法です。2 つ目は、閾値 cron が各実行時に何を行うか、そしてリンクが一夜にしてバイラルになった場合に重複ディールの作成をどう防ぐかです。3 つ目は、Elido SDK と小さな webhook ハンドラーを使って、3 つのデフォルト閾値を超えてカスタムクリック数、UTM スコープのトリガー、カスタム Pipedrive フィールドまで連携を拡張する方法です。

Pipedrive は 2026 年 5 月 22 日に Elido で Live になりました。それ以前はステージ ID とトークンローテーション周りのエッジケースを解消しながら 2 週間 Beta 状態でした。連携コードはセルフホストで読みたい場合 services/api-core/internal/integrations/pipedrive/ にあります。この記事のすべての内容はロードマップではなく、現在リリース済みの内容に対応しています。

2 分で Pipedrive を接続する

Elido ワークスペースの連携カタログを開き、Pipedrive カードをクリックします。Connect モーダルが最初に求めるのは 1 つだけ：個人 API トークンです。Pipedrive アカウントのプロフィールメニューから「個人設定」を選択し、「API」タブで取得できます。Pipedrive 公式ガイドの how to find the Personal API token にスクリーンショット付きの正確な手順があります。UI は四半期ごとに変わる可能性があるため、そちらを参照してください。

トークンを貼り付けます。Elido はバックグラウンドで 2 つの処理を行います。Pipedrive API に対して GET /users/me を呼び出してトークンを検証し、トークンが有効であることを確認しつつ、どの Pipedrive 企業のトークンかを取得します。また、その企業のパイプラインとステージのリストを取得するため、モーダルの次のステップでは自由記述フィールドではなく実際の選択肢が表示されます。

モーダルはさらに 2 つの質問をします。新しいディールをどのパイプラインに作成するか？そのパイプラインのどのステージか？ドロップダウンにはあなたの Pipedrive のライブデータが表示されます。「インバウンド」「アウトバウンド」「パートナー」という 3 つのパイプラインがあれば、その 3 つが表示されます。マーケティング主導のシグナルには通常インバウンドを選び、最初の適格ステージを選択してください。「接続」をクリックします。

接続後のトークンの扱いについて。Elido は Postgres に書き込む前にトークンを暗号化します。テナントごとのデータ暗号化キーを使ったエンベロープ暗号化で、そのキーはワークスペース KMS キーによってラップされます。integration_credentials テーブルに保存されるのはこの暗号化された blob です。平文のトークンは単一の API 呼び出しの間だけメモリに存在し、デバッグ verbosity でも絶対にログに記録されません。Pipedrive でトークンをローテーションすると、次の cron 実行が 401 を受け取り、Elido は連携を「再認証が必要」としてマークします。これはサイレントな障害ではなく、ワークスペースにバナーとして表示されます。ローテーションの衛生管理はあなたの責任で、障害は明示的に通知されます。

パイプラインピッカーは小さくても重要な詳細です。CRM 連携でよくある失敗は、会社にパイプラインが 1 本だった時期に連携を構築し、今は 6 本あるために誤ったパイプラインにディールが作成されることです。接続時にユーザーが選択し、1 か月前のキャッシュではなく現在のリストを表示することで、こうした問題のクラス全体を排除できます。閾値履歴を失うことなく、いつでも再接続してターゲットのパイプラインを変更することもできます。

5 分ごとの cron が実際に行うこと

services/api-core には click_threshold_hook というジョブがあります。5 分ごとに実行され、各 tick で Pipedrive が接続されているワークスペースごとに、以下の 3 つを順番に実行します。

1 つ目は、過去 6 分間に更新されたリンクごとのクリック合計を ClickHouse に問い合わせます。遅延イベントをカバーするため 1 分のバッファを加えています。ClickHouse は日付でパーティション化された clicks テーブルにクリックイベントを保存し、クエリするロールアップはショートリンク ID をキーとするマテリアライズドビューです。このクエリはテーブル全体ではなく、前回の cron 実行以降に合計が変化したリンクのみを返します。50,000 のアクティブリンクを持ち通常のクリックパターンのワークスペースでは、このクエリは 200ms 以内に収まります。

2 つ目は、各リンクの新しい合計を記録された閾値と比較します。デフォルト閾値は 100、1,000、10,000 です。各リンクについて、Elido はリンク ID をキーとした小さな link_threshold_state 行で、これまでに到達した最高閾値を追跡しています。前回の実行でリンクが 80 クリックで今回が 240 なら、比較によって 100 の閾値を超えたことがわかり、1,000 はまだ到達していないことがわかります。100 を到達済みとしてマークし、ディール作成を 1 件キューに入れます。80 から 1,200 に跳んだリンクでは 100 と 1,000 の両方を超えているため、2 件をキューに入れます。

3 つ目は、キューに入った各ディールについて、Elido が Pipedrive の Deals API に /deals への POST を呼び出します。ボディには Connect ピッカーのパイプライン ID とステージ ID を設定し、Link <slug> が <閾値> クリックに到達 のような読みやすい名前をつけ、UTM ソース・ミディアム・キャンペーンをディールノートに書き込み、そのリンクの Elido アナリティクスビューへのクリッカブルリンクも添えます。ワークスペースにカスタムフィールドが設定されている場合は、リンク ID をそのフィールドにも保存します。これにより、後で特定の Elido リンクに紐付いたすべてのディールを Pipedrive で検索できます。

この cron が行わないことも挙げておきます。Pipedrive の 5xx に対して無限リトライは行いません。Pipedrive が 500 または 503 を返した場合、同じ cron tick 内でエクスポネンシャルバックオフで 2 回リトライし、その後は次の tick に委ねます。Pipedrive のレート制限は企業トークンごとに実質 2 秒あたり 100 リクエストで、ほとんどのチームが達するボリュームには十分なマージンがあります。テスト・社内用・または個人設定で CRM 同期をオプトアウトしたワークスペースメンバー所有のリンクに対してもディールは作成しません。

重複防止は最も多くのイテレーションが必要だった部分です。最初のバージョンにはレース条件がありました。2 つの cron ポッドが重なって実行された場合、両方が同じリンクで 100 を超えたと見なし、両方がディールを POST する可能性がありました。各 cron tick の開始時にワークスペース ID に対する Postgres アドバイザリーロックと、link_threshold_state の (link_id, threshold) に対するユニーク制約の組み合わせで解決しました。2 つ目のポッドが重複行の挿入を試みると Postgres が拒否し、キューに入った POST は Pipedrive に到達する前に破棄されます。二重の安全策です。

3 つのデフォルト閾値を超えた拡張

搭載されている閾値は 100、1,000、10,000 です。ほとんどのチームはこれらを維持します。営業のストーリーに自然に合致するからです。100 クリックはちょっと確認する価値のあるソフトなシグナルです。1,000 は電話をかける価値のあるキャンペーンです。10,000 は担当者がすでに動いているべき十分にホットな状態です。とはいえ、別の数値を使いたい場合もあり、SDK はそれをサポートしています。

Elido の Pipedrive 連携はワークスペースレベルでカスタム閾値リストを受け付けます。PATCH /v1/workspaces/:id/integrations/pipedrive エンドポイントに {"thresholds": [50, 500, 5000, 50000]} のような JSON ボディを送ることで設定できます。cron は次の tick で新しいリストを使います。状態テーブルは履歴を保持するため、閾値を変更しても過去のディールは遡及して作成されず、将来の通過でのみ新しい設定が反映されます。

より豊かなトリガーには、SDK が任意のサービスから登録できる CreateDeal フックを公開しています。典型的なケース：リンクが閾値を超えかつ UTM ソースが有料ソーシャルキャンペーンのときだけディールを作成したい（オーガニックブログは除く）。これはフック内の 1 行のフィルターです。もう一つよくあるケース：特定の Elido フォルダー内のリンクにのみ発火させる（そのフォルダーがキャンペーンフォルダーで、それ以外はノイズ）。同じフックで、営業チームが使うタクソノミーに応じた Deal Source や Lead Channel などの Pipedrive カスタムフィールドを設定することもできます。コンバージョン転送ガイドには広告プラットフォーム向けの同じフックパターンが記載されており、Pipedrive のケースは構造的に同一です。

カスタムフィールドについての注記。SDK は人が読めるラベルと Pipedrive が内部で使うハッシュ化された API キーの両方を受け付けます。接続した企業に存在しないラベルを参照した場合、ディールは引き続き作成されますが、欠落フィールドはエラーではなく警告としてログに記録されます。カスタムフィールドの欠落が実際の営業シグナルをブロックすることはあってはなりません。

キャンペーンあたり多数のリンクを持つチームは、フォルダー単位で閾値を集計したい場合があります。ワークスペース連携設定に aggregation: "folder" を設定すると、cron がフォルダーごとにクリック合計をグループ化して合計を確認します。ディールにはフォルダー名が付き、最も貢献度の高い上位 3 リンクがノートに記載されます。

トークンの保管場所とローテーション方法

セキュリティレビューで必ず出てくるため、簡潔にまとめます。個人 API トークンはテナントごとのデータ暗号化キーを使った AES-256-GCM で保管時に暗号化されます。DEK 自体は KMS のワークスペースレベルキーによってラップされており、api-core プロセスだけが解除できます。ログ・バックアップ・エラートレースのいずれにも平文トークンは存在しません。リクエスト途中で Pipedrive の 401 を強制するフォルト注入でテストし、エラーパスが Sentry に届く前にレスポンスからトークンを消去することを確認しました。

ローテーションの手順：Pipedrive で新しい個人 API トークンを生成し、古いトークンを失効させ、新しいトークンを Elido の Connect モーダルに貼り付けます。連携が新しいトークンを検証してその場で置き換え、次の cron tick からそれを使います。古いトークンを失効させた後に Elido の更新を忘れると、次の cron tick が 401 を受け取り、連携が「再認証が必要」状態になります。ワークスペースダッシュボードに黄色のバナーとして表示されます。サイレントな失効トークンはありません。

セルフホストでは KMS はプラガブルです。デフォルトはファイルベースで、HashiCorp Vault またはクラウド KMS に差し替えられます。ADR-0036 に詳細が記載されています。

より広いファネルの中での位置付け

クリックから Pipedrive ディールを作成するトリガーは、より大きなパターンの一部です。クリック数は先行指標であり収益数字ではないため、通常は残りの営業コンテキストが集まる CRM に流し込むことになります。ディールが引き渡し点です。マーケティングが仕事を完了し、営業が引き取ります。そこから先は通常の Pipedrive ワークフロー（担当者への割り当て、スコアリング、ステージ移動、クロージング）が機能します。

広告プラットフォームにコンバージョンも転送している場合、同じクリックデータが両方のフローを供給します。コンバージョントラッキング機能が広告側を担当し、Pipedrive 連携が CRM 側を担当し、2 つが同じイベントを取り合うことはありません。この組み合わせが最も多く見られるのはマーケター向けソリューションページで、スタック全体が有料獲得からブランドリンクを経由して CRM ファネルへと続いています。

数値を正直に保ちたいアナリストには、上流の懸念事項を扱う 2 つの過去記事があります。Short link analytics: what to measure はどのクリックメトリクスが実際に収益と相関するかを扱い、Track UTM end to end はディールノートをノイズではなく有用なものにする UTM 衛生管理を扱っています。どちらもこの連携とよく合います。Pipedrive が作成するディールは、それが運ぶ UTM データと同じ価値しか持たないためです。

プランに関する最後の詳細です。Pipedrive 連携はすべての Elido 有料ティアに含まれており、14 日間のトライアルにも含まれているため、登録前に閾値リストを検証できます。無料ワークスペースはテスト用に接続を作成できますが、無料リンクに対して cron は実行されません。ティアごとの内訳は料金ページにあります。

セットアップチェックリスト

印刷して、一度実施してください。

1. Pipedrive で：プロフィールメニュー、個人設定、API タブ、トークンをコピー。
2. Elido で：連携、Pipedrive カード、接続。
3. トークンを貼り付け。検証を待つ。
4. パイプラインとステージを選択。デフォルト：インバウンドと最初の適格ステージ。
5. 接続をクリック。
6. 任意：100/1k/10k が営業プロセスに合わない場合は閾値リストを編集。
7. 任意：UTM フィルターやフォルダー集計のためのカスタム CreateDeal フックを登録。
8. 5 分待つ。テストクリックを送る。最初のディールが作成されるのを確認。

以上です。セルフホストの場合は、kubectl get cronjob api-core-click-threshold-hook が有効なスケジュールを返すことを確認して、cron が有効になっていることも確認してください。Elido Cloud では cron は管理されています。