%20(%E8%83%8C%E6%99%AF%E3%81%82%E3%82%8A).png?width=130&height=39&name=%E6%9C%80%E7%B5%82Start%20Link%20(500%20x%20150%20px)%20(%E8%83%8C%E6%99%AF%E3%81%82%E3%82%8A).png "StartLink"){kind=logo}
この記事の結論
カスタムイベントは、プロパティでは残せない行動の履歴を記録する仕組みです。主オブジェクトと内部名は後から変えられないため、作成前の設計が成否を分けます。
HubSpotのカスタムイベントとは、「いつ・誰が・何をしたか」という行動の履歴を、発生した1回ごとに記録する仕組みです。 プロパティが「いまの状態」を1つの値で持つのに対し、カスタムイベントは「何度起きたか」「最後はいつか」を残せます。製品の利用、資料の閲覧、申込みの途中離脱といった行動を、コンタクトのタイムラインやレポートで扱えるようになります。
ただし、作ってから直せない項目が複数あります。イベントの主オブジェクトと内部名は、作成後に変更できません。記録を始めてから設計の誤りに気づくと、作り直しとデータの再送が必要になります。行動データは「とりあえず送ってみる」ではなく、使い道から逆算して設計するのが原則です。
この記事では、カスタムイベントを使う目的の整理から、作成前に決める項目、記録方法の選び方、セグメントとワークフローでの使い方、運用上の注意までを、公式ナレッジで確認できた範囲で解説します。
- プロパティとイベントの線引き ── 「状態」はプロパティ、「履歴」はイベントと分けると設計が迷いません
- 作成前に決める5項目 ── 後から変えられない主オブジェクト・内部名・マッチIDを先に確定します
- 記録方法は5種類から選ぶ ── 行動の発生場所（Web・自社システム・外部サービス・過去データ）で決まります
- セグメントとワークフローでの使い方 ── 使えること、使えないこと（制約）を公式の記載に沿って整理します
- 運用の落とし穴 ── 重複送信・配信エラー・削除の不可逆性への備え方をまとめます
カスタムイベントで解決する課題と、プロパティとの使い分け
カスタムイベントが必要になるのは、「行動の回数や時系列」を営業・マーケティング・カスタマーサクセスの判断に使いたいときです。たとえば「直近でログインした日」だけなら、日付のプロパティで足ります。しかし「過去30日に何回ログインしたか」「どの機能を使ったか」「ログインの間隔が空いていないか」を見たい場合、上書きされるプロパティでは履歴が残りません。
「状態」はプロパティ、「履歴」はイベント
判断のしやすさから、記録したい情報を次のように分けて考えます。
| 観点 | プロパティ | カスタムイベント |
|---|---|---|
| 持つもの | 現在の状態（1つの値） | 発生した1回ごとの記録 |
| 更新の仕方 | 新しい値で上書き | 発生のたびに1件追加 |
| 向く情報 | 担当者・ステージ・契約終了日 | ログイン・申込み・機能の利用 |
| 見たいこと | 「いま何か」 | 「何回、いつ、どの順に」 |
上書きで困らないものはプロパティ、時系列や回数が意味を持つものはイベントです。両者は排他ではありません。イベントの発生に応じてワークフローでプロパティを更新し、「最終利用日」のような要約値を作る併用が、一覧表示や分析で扱いやすい構成になります。プロパティ側の設計はCRMデータベース設計の基本も参考になります。
イベントが向く場面と向かない場面
イベントは、使い道が決まってから作ります。使い道を決めずに「取れる行動をすべて送る」と、後で何を見ればよいか分からなくなります。次のどれにも当てはまらないイベントは、作らないほうが運用が軽くなります。
- 行動の回数や直近の発生を、セグメントの条件にしたい
- 行動をきっかけに、ワークフローで担当者への通知やメール送信を動かしたい
- 行動の推移を、レポートで期間ごとに比較したい
公式ナレッジによると、カスタムイベントはMarketing Hub・Sales Hub・Service Hub・Data Hub・Content Hub・Revenue Hubの各製品のProfessionalとEnterpriseで利用できます（記録方法のうちWebhookはData HubのProfessionalまたはEnterpriseが必要です）。まず対象プランを確認してから設計に入ります。
作成前に決める5項目｜後から変えられないものを先に確定する
カスタムイベントの設計で最も重要なのは、後から変えられない項目の見極めです。開発者向けの公式ドキュメントと、公式ナレッジの記載を突き合わせると、次の5項目が作成前の決定事項になります。
5項目の判断表
| 決める項目 | 後から変更 | 判断の基準 |
|---|---|---|
| 主オブジェクト | 不可 | コンタクト・会社・取引・チケット、または対象なし。行動の主体で決める |
| 内部名 | 不可 | 小文字の英字・数字・アンダースコアのみ、先頭は英字、50文字以内 |
| マッチID（任意） | 作成時に設定 | 社内システムのIDでレコードに紐づけたいときに使う。照合先のプロパティは一意である必要がある |
| プロパティの名前と型 | 型の変更は不可（削除して作り直し） | 後で絞り込みや集計に使う値だけを持たせる |
| 既定のイベントプロパティ | 作成時に選択 | 不要なら外せる。標準で含める設定になっている |
出典：HubSpot開発者ドキュメント（カスタムイベントの定義）とカスタムイベントの作成（HubSpotナレッジ）
主オブジェクトを間違えたときの影響
公式ナレッジには、主オブジェクトは後から変更できない、対象なしで作ったイベントは後からCRMのレコードにひも付けられない、と明記されています。たとえば、顧客企業単位で利用状況を見たいのに、コンタクトを主オブジェクトにしてしまうと、会社単位の集計に別の工夫が必要になります。作成前に「この行動を、誰（どのレコード）の行動として見たいか」を一文で書き出しておくと、取り違えを防げます。
内部名とプロパティ型の決め方
内部名は、後ろに続く送信処理やレポートの定義が参照するキーです。表示名（ラベル）は更新できますが、内部名は変えられません。命名は「対象_動詞（過去形や完了形）」のように揃えておくと、一覧で並べたときに意味が通ります。
プロパティの型は、文字列・数値・日時・日付・真偽値・列挙の中から選びます。数値は小数点以下1桁までという記載があるため、金額や比率を厳密に持たせたい場合は、別の持ち方を検討します。列挙型は選択肢を先に登録しておく必要があり、データを送る前に値を確定させます。型を変えるときは、プロパティを削除して作り直す必要があります。削除しても過去の発生分の値は残りますが、新しい発生分には使われなくなる、というのが公式の説明です。
記録方法を5種類から選ぶ｜行動が起きる場所で決める
公式ナレッジでは、「データ管理」の「イベント管理」から、カスタムイベントの作成方法を5つ案内しています。どれを選ぶかは、行動が起きる場所と、保守する担当者で決まります。
5つの方法の比較
| 方法 | 向く場面 | 事前に必要なもの |
|---|---|---|
| API送信 | 自社の製品・業務システムの行動を記録する | 開発側での送信処理 |
| JavaScriptコード | 自社Webサイト上の行動を記録する | サイトのトラッキングコードへの追記 |
| イベントビジュアライザー | Webページの閲覧・要素のクリックをコードなしで記録する | 対象サイトにトラッキングコードがあること |
| スプレッドシートのインポート | すでに発生した過去の行動を取り込む | コンタクトのメールアドレスと発生日時の列 |
| Webhook | 外部サービスが通知する行動を受け取る | Data HubのProfessionalまたはEnterprise |
スプレッドシートの取り込みで押さえる制約
過去データを取り込める反面、制約があります。公式ナレッジでは、取り込みで関連付けられるのはコンタクトのみで、メールアドレスと「発生日時」の列が必要とされています。複数選択の列挙プロパティは取り込めません。過去の行動を後から使いたい場合は、移行の段階で列の形を整えておく必要があります。
選び方の順番
次の順で絞ると、迷いが減ります。
- 行動が起きるのは、自社のWebサイトか、製品・業務システムか、外部サービスか
- Webサイトなら、コードを書けるかどうかで、JavaScriptコードかイベントビジュアライザーを選ぶ
- 製品・業務システムなら、API送信を選び、送信側の担当者と保守を決める
- 外部サービスなら、Webhookの通知項目がHubSpotのプロパティと型が揃うかを確認する
- 過去の履歴を使いたいなら、取り込み用のファイルを別に用意する
Webhookで受けたイベントは、コンタクトのタイムラインには表示されないと公式ナレッジに記載があります。担当者がタイムラインで行動を確認する運用を想定している場合は、方法の選択に影響します。
イベントを作成して送信する手順（API送信の場合）
ここでは、自社システムからの記録で最もよく使われるAPI送信を例に、公式ナレッジと開発者ドキュメントに沿った手順を整理します。画面の項目名は日本語版で表記が異なる場合があるため、実際の画面と照らして読み替えてください。
定義を作る手順
- 「データ管理」の「イベント管理」を開き、イベントの作成から、カスタムイベントを作成する
- 方法として「API送信」を選び、イベント名と説明を入力する
- プロパティを追加する。名前・フィールドタイプ・説明を設定し、必要なだけ追加する
- 主オブジェクト（コンタクト・会社・取引・チケット）または「対象なし」を選ぶ
- 必要な場合は、レコードとの照合に使うマッチIDを設定する。照合先のプロパティは一意の値を要求する設定にしておく
- 追跡用のIDを控えて、イベントを作成する
発生を送る手順
発生の送信には、開発者ドキュメントの POST /events/v3/send を使います。公式の記載から、実装時に必要な点を次の表にまとめます。
| 項目 | 内容 | 設計上のポイント |
|---|---|---|
| イベント名 | pe{ポータルID}_{内部名} の形式 |
作成後の定義で正式な名前を確認して使う |
| レコードの特定 | オブジェクトID・マッチID・メールアドレス・utkのいずれか | 複数送ると、マッチID・オブジェクトID・メール・utkの順に優先される |
| 発生日時 | 省略すると送信した時刻になる | 過去分の送信は日時を指定して再現する |
| 一意のID（uuid） | 同じIDを1年以内に再送すると、最初の1件だけが受け付けられる | 再送に備え、業務側の一意のキーから作る |
| バッチ送信（バッチ用エンドポイント） | 1回あたり500件まで。上限は /events/v3/send ではなく、バッチ用エンドポイントの仕様 |
大量に送るときは、単発送信と別のエンドポイントであることを確認して使う |
出典：イベント発生の送信（HubSpot開発者ドキュメント）
特に、uuid は重複送信の防止に使えます。送信処理が失敗して再実行する運用では、同じ行動に毎回同じuuidを付ける設計にしておくと、二重計上を避けられます。
上限値
公式ドキュメントには、1回の発生に持たせられるプロパティは50個まで、値の長さは原則256文字（名前にurl・referrer・linkを含むものは1,024文字）という上限が記載されています。プロパティは「後で絞り込みや集計に使う値」だけに絞る設計が、上限の面からも求められます。
セグメントで使う｜行動の有無を条件にする
行動の記録は、セグメントの条件として使えます。ここでは、公式ナレッジで確認できた範囲に絞って説明します。
セグメントでの設定の流れ
セグメントは、「CRM」の「セグメント」から作成します。作成するセグメントは、メンバーが条件に応じて自動更新される動的（アクティブ）なものと、保存時点の内容で固定される静的なものがあります。イベントを条件にするときは、フィルターを追加し、フィルターカテゴリーで「イベント」を選んで、対象のイベントを検索して選びます。そのうえで演算子を選び、項目の型に応じた条件を設定します。
アクティブと静的の使い分け
| 種類 | メンバーの更新 | イベントを使う場面 |
|---|---|---|
| アクティブ（動的） | 条件に合わせて自動で出入りする | 継続的に行動を監視し、配信や通知の対象に使う |
| 静的 | 保存時点の内容で固定される | ある時点の対象を記録して、施策の効果を後から検証する |
継続的に配信や通知に使うなら、アクティブセグメントが基本です。施策の対象を固定して比較したい場合は静的にします。
公式ナレッジで確認できなかった点
セグメントのイベントフィルターについて、公式のセグメント作成ページに載っているイベントの例は、CTAの操作が中心です。カスタムイベントの回数や期間をどう指定できるかは、このページには記載がありません。そのため、「過去30日に3回以上」のような条件が組めるかは、実際の画面で演算子の選択肢を確認してから設計します。また、HubSpotのコミュニティでは、セグメントで使えるのはイベントのプロパティで、付加情報（extraData）は条件にできないという報告があります。条件に使う値は、必ずイベントのプロパティとして定義しておきます。
ワークフローで使う｜行動を起点に動かす
行動をきっかけに自動化を動かす使い方です。トリガーの種類と、制約を正しく理解しておかないと、「動かない」原因の切り分けに時間がかかります。
カスタムイベントを起点にする設定
「自動化」の「ワークフロー」で、登録トリガーに Custom event occurs を選び、対象のイベントを指定します。トリガー内での選択手順や分類名は、画面の表記を確認してください。さらに条件を追加できます。公式ナレッジの記載では、登録の既定は「最初にトリガー条件を満たしたときだけ」で、繰り返し登録したい場合は再登録の設定を「はい」にします。
動かないときに確認する制約
公式ナレッジには、Custom event occurs トリガーについて次の制約が明記されています。
| 制約 | 意味すること |
|---|---|
| Custom event occurs トリガーは既存のコンタクトだけが登録される | コンタクトになる前に発生した行動では、登録されない |
| 有効化した後に発生した行動だけが対象 | 過去の発生分を遡って登録することはできない |
| トリガーのテストができない | 動作確認は、検証用のレコードで実際に発生させて行う |
| イベントトリガーはスケジュールトリガーと併用できない | 定期実行と組み合わせたい場合は、ワークフローを分けて設計する |
過去に発生した行動を持つコンタクトを対象にするときは、イベントのトリガーではなく、条件で絞った登録トリガーや手動の登録を使います。ワークフロー全体の設計の考え方は、MAワークフロー設計ガイドにまとめています。
行動の点数化に使う場合
行動の回数を、リードの優先度に反映させたい場合は、イベントの発生をワークフローでプロパティの更新につなげる方法があります。スコアの設計の考え方はリードスコアリングの設計方法で整理しています。
設計例｜行動を3つに絞って定義する
最初から多くのイベントを作る必要はありません。使い道が確定した行動だけを、少数に絞って定義します。ここでは、会員向けの製品やサービスを提供する企業を想定した、一般的な設計例を示します。送信元は、Webサイト（JavaScriptコード）、自社システム（API送信）、外部サービス（Webhook）のいずれかになります。自社の状況に当てはめる際の叩き台としてお使いください。
イベント設計表の例
| イベント（表示名／内部名の例） | 記録するタイミング | 持たせるプロパティの例 |
|---|---|---|
利用開始／service_started |
初回の利用を始めたとき | プラン種別（列挙）、開始経路（列挙） |
機能の利用／feature_used |
主要機能を操作したとき | 機能名（列挙）、利用回数（数値） |
管理者の変更申請／admin_change_requested |
管理者の変更を申請したとき | 申請区分（列挙）、申請元の画面（文字列） |
この3つに絞る理由
利用開始は、自社システムからAPI送信し、カスタマーサクセス担当がワークフローの通知で初動の声かけをします。機能の利用は、Webの操作を JavaScriptコードかイベントビジュアライザーで記録し、マーケティング担当がセグメントの画面で定着度の低い層を抽出します。管理者の変更申請は、外部の申込みサービスからWebhookで受け、窓口の担当者が通知で変更に気づきます。いずれも、使い道が先にあります。記録できる行動のうち、使い道が決まっていないものは、設計表に入れません。
使い道を決める3つの問い
イベントを追加する前に、次の3つに答えられるかを確認します。答えられない行動は、いったん見送ります。
- このイベントが発生したら、誰が、どんな行動を取るのか
- 回数や直近の発生日を、どのセグメントやレポートで使うのか
- イベントを取りやめたときに、困る人がいるか
運用の落とし穴｜配信エラー・削除・上限への備え
カスタムイベントは、一度動き始めた後の保守で品質が決まります。設計と同じ重さで、運用の手順を決めておきます。
配信エラーの確認
イベント管理には、発生数の推移を比較できるモニタリング用の画面と、同期に失敗した配信エラーの一覧があります。公式ナレッジには、定義にないプロパティが送られたときに出る「Unknown Property」のエラーを、画面の操作からイベントにプロパティを追加して解消する手順が載っています。送信側の担当者が定義と違う項目を送り始めたときの検知に使えます。週に1回など、確認の頻度を決めておきます。
削除は取り消せない
開発者ドキュメントによると、イベント定義を削除すると、その発生データがすべて完全に削除され、ワークフローやレポートからも外れます。削除した名前は再利用できません。「使わなくなった」ことと「過去の記録も不要」は別の判断です。削除の前に、依存するワークフロー・セグメント・レポートを洗い出します。
運用の判断表
| 場面 | 確認すること | 担当を決めておく項目 |
|---|---|---|
| 新しい行動を追加したい | 使い道・主オブジェクト・内部名を設計表に追記したか | 設計表の管理者 |
| 送信側の仕様を変えたい | 定義にないプロパティを送っていないか | 送信側の担当者 |
| イベントを廃止したい | 依存するワークフロー・セグメント・レポートがないか | HubSpotの管理者 |
StartLinkの支援の進め方：使い道の整理から運用の定着まで
StartLinkは、HubSpotゴールドパートナーとして、行動データの設計を次の工程で支援します。最初に使い道が明確な1〜2個のイベントから始め、効果を確認してから広げる進め方が基本です。企業様（チーム）によって最適な形は異なりますので、行動を発生させるシステムの構成、記録の担当、セグメントとワークフローの使い道を整理したうえで、イベントの数と記録方法を決めます。
| 工程 | この記事のテーマでの内容 | 成果物 |
|---|---|---|
| 現状の整理・要件定義 | 記録したい行動の洗い出し、使い道（セグメント・ワークフロー・レポート）の一文化、送信元システムの確認 | 行動の一覧と使い道の対応表 |
| 設計・構築 | 主オブジェクト・内部名・プロパティの型の確定、記録方法の選定、イベントの作成 | イベント設計表、定義の作成 |
| テスト・検証 | 検証用レコードでの発生確認、配信エラーの有無、トリガーの動作確認 | 検証結果の記録 |
| 定着・運用改善 | 配信エラーの確認頻度、追加・廃止の判断手順、依存関係の洗い出し | 運用の判断表 |
自社システムの行動をHubSpotに送る設計は、API連携の観点からCRM API連携の設計ガイドとあわせて検討すると、見落としが減ります。
よくある質問
Q1. カスタムイベントとカスタムプロパティは、どう使い分けますか。
現在の状態を1つの値で持つならプロパティ、発生のたびに1件ずつ残したい行動はカスタムイベントです。上書きされても困らない情報はプロパティで足ります。回数・時系列・順序が判断に必要な場合だけ、イベントを使います。
Q2. 作成した後に、主オブジェクトや内部名を変更できますか。
変更できません。公式ナレッジと開発者ドキュメントの両方で、主オブジェクトと内部名は作成後に変更できないと記載されています。表示名と説明は更新できるため、迷うときは内部名を一般的な表現で作り、表示名で補います。
Q3. 過去に起きた行動も、ワークフローで拾えますか。
イベントを起点とする登録トリガーは、有効化した後に発生した行動だけが対象です。過去分を対象にする場合は、条件で絞る登録トリガーや手動の登録を使います。過去の履歴そのものは、スプレッドシートのインポートで取り込めますが、コンタクトのみが対象で、メールアドレスと発生日時の列が必要です。
Q4. コンタクトになる前の匿名の訪問者の行動は、記録されますか。
公式ナレッジのイベント分析の記載では、匿名の訪問者が後にコンタクトになると、過去のイベントデータがコンタクトのタイムラインに追加されます。一方、ワークフローのトリガーは既存のコンタクトにしか動かないため、コンタクトになる前の行動では登録されません。
Q5. 同じ行動を二重に送ってしまったら、どうなりますか。
送信時にuuidを指定している場合、同じuuidを1年以内に再送すると、最初の1件だけが受け付けられ、後のものは拒否されます。再実行がありうる送信処理では、業務側の一意のキーからuuidを作っておくと、二重計上を避けられます。
まとめ：カスタムイベントは「使い道」から逆算して設計する
- 履歴が必要な行動だけをイベントにする ── 状態はプロパティ、回数や時系列はイベントで持ちます
- 後から変えられない項目を先に確定する ── 主オブジェクト・内部名・プロパティの型は、作成前に決め切ります
- 記録方法は行動が起きる場所で選ぶ ── Web・自社システム・外部サービス・過去データで方法が分かれます
- セグメントとワークフローの制約を確認する ── トリガーは有効化後の発生分が対象で、テストはできません
- 運用の担当を決める ── 配信エラーの確認と、削除前の依存の洗い出しを手順にします
最初の一歩は、記録したい行動を3つまで書き出し、それぞれの使い道（セグメント・ワークフロー・レポート）を一文で書くことです。使い道を書けない行動は、設計表から外します。
自社の状況に当てはめた進め方を検討したい場合は、CRM特化型コンサルティングの StartLink までお問い合わせください。HubSpotの導入・設計の支援内容はHubSpot導入支援サービスで、Data Hubの機能の全体像はHubSpot Data Hubの解説で確認できます。運用の取り決めの作り方はCRM運用ルール設計ガイドも参考にしてください。
参考にした公式情報
記事の内容を、そのまま実務に落とし込みたい方向け
HubSpotゴールドパートナーのStartLinkが、HubSpot導入・AI活用・CRM整備・業務効率化までをまとめて支援しています。記事で気になったテーマを、そのまま相談ベースで整理できます。
次に読む
株式会社StartLinkは、事業推進に関わる「販売促進」「DXによる業務効率化（ERP/CRM/SFA/MAの導入）」などのご相談を受け付けております。 サービスのプランについてのご相談/お見積もり依頼や、ノウハウのお問い合わせについては、無料のお問い合わせページより、お気軽にご連絡くださいませ。
著者情報
