%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カスタムコードによるCRM拡張の3つの活用パターン。ワークフロー内カスタムコード・API連携・カスタムカードの実装方法と設計の注意点。
HubSpotカスタムコードによるCRM拡張の3つの活用パターン。ワークフロー内カスタムコード・API連携・カスタムカードの実装方法と設計の注意点。
「HubSpotの標準機能だけでは、自社固有のビジネスロジックを実装できない」「受注後の請求処理を自動化したいのに、標準のワークフローでは表現しきれない」「外部システムとの連携を自動化したいが、iPaaSでは対応しきれない」——こうしたケースでは、カスタムコードによるCRM拡張が有力な選択肢になります。
HubSpotのカスタムコード機能とは、ワークフロー内でNode.jsやPythonのコードを実行したり、APIを使って外部システムと連携したり、レコード画面にカスタムカード（UI Extensions）を追加したりできる、開発者向けの拡張機能です。標準機能と外部サービスの「隙間」に落ちてしまう自社固有の処理を、HubSpotの中に組み込むための仕組みと考えてください。
この記事では、カスタムコードの3つの活用パターンとそれぞれの実装方法、標準機能やiPaaSとの使い分け基準、開発・運用の注意点を解説します。
本記事は「HubSpot Enterprise活用ガイド｜大企業が使いこなすための設計と運用の勘所」シリーズの一部です。本記事はStartLinkの「HubSpot完全ガイド」関連記事です。
この記事でわかること
HubSpotの標準機能では足りない処理をカスタムコードで実装したい方に向けて、3つの活用パターンと実装の進め方、使い分けの判断基準を整理しています。
- HubSpotカスタムコードの3つの活用パターン — ワークフロー内カスタムコード・HubSpot API・カスタムカード（UI Extensions）という3つの拡張手段の全体像を解説します。
- ワークフロー内カスタムコードの実装方法 — 取引が「受注」ステージに移行した際に、月額料金×契約期間分の請求カスタムオブジェクトレコードを自動生成する実装例を紹介します。
- HubSpot APIの基本と主な活用シーン — Private App Tokenによる認証、主なAPIカテゴリ、レート制限の数値まで押さえます。
- カスタムカード（UI Extensions）の概要と設計 — レコード画面の右側パネルに独自のUIコンポーネントを表示する仕組みと活用例を紹介します。
- 標準機能・iPaaS・カスタムコードの使い分け基準 — メンテナンスコストを抑えながら自社に最適な拡張を選ぶための判断軸と、開発時の注意点を整理します。
「HubSpotの標準機能だけでは、自社固有のビジネスロジックを実装できない」とお感じの方に向けて書いています。最後まで読むと、自社の要件に対してどの拡張手段を選び、どこから着手すればよいかを判断できるようになります。
カスタムコードとは——標準機能で届かない領域を埋める仕組み
HubSpotは標準機能だけでもかなりの業務をカバーできますが、すべての企業の要件を網羅しているわけではありません。
自社固有の計算ロジックや外部システムとの細かい連携など、標準では表現しきれない処理を補うのがカスタムコードの役割です。ここでは、カスタムコードが担う領域と3つの活用パターンの全体像を整理します。
カスタムコードが担う役割
カスタムコードは、HubSpotの標準機能と外部サービスの間にある「隙間」を埋めるものです。例えば、次のような処理は標準のワークフローアクションでは実現しにくい領域です。
- 請求レコードの一括生成 ── 受注ステージへの移行をトリガーに、契約期間分の請求レコードをまとめて生成する
- 外部APIの呼び出し ── フォーム送信時に、外部の与信チェックAPIを呼び出す
CRMを単なるデータベースとしてではなく、受注から請求までつながる業務のエンジンとして使う場合、この「隙間」をどう埋めるかが運用の質を左右します。
3つの活用パターンの全体像
HubSpotのカスタムコードによる拡張手段は、大きく3つに分類できます。
| パターン | できること | 向いているケース |
|---|---|---|
| ワークフロー内カスタムコード | Node.jsまたはPythonで独自処理を実行 | 受注時の請求レコード一括生成、外部API呼び出し、複雑な条件分岐 |
| HubSpot APIによる外部連携 | REST APIで外部システムと双方向にデータをやり取り | 基幹システムとの受注データ同期、BIツールへのエクスポート |
| カスタムカード（UI Extensions） | レコード画面に独自のUIコンポーネントを追加 | 外部データのリアルタイム表示、外部APIを呼ぶアクションボタン |
どれか1つだけを使うのではなく、要件に応じて組み合わせるのが実務的な使い方です。
全体フローの中での位置づけ
カスタムコードはその流れの中で、標準機能だけでは途切れてしまう箇所をつなぐ役割を果たします。
例えば「取引の受注→請求レコード生成→会計システムへの連携」という流れは、ワークフロー内カスタムコードとAPI連携を組み合わせることで、HubSpot内に留めたまま自動化できます。
個別の機能としてではなく、業務全体のフローのどこを補強するかという視点で設計することがポイントになってきます。
ワークフロー内カスタムコードの実装方法
ワークフロー内カスタムコードは、HubSpotの自動化の中にNode.jsまたはPythonのコードを直接埋め込める機能で、Professional以上のプランで利用可能です。
トリガーの発動から外部API呼び出し、CRMレコードの作成・更新までを1つのワークフローで完結させられます。
基本的な実装の流れ
実装は以下の6ステップで進めます。
| ステップ | 内容 |
|---|---|
| 1 | ワークフローを新規作成（または既存ワークフローを編集） |
| 2 | アクションに「カスタムコード」を追加 |
| 3 | 言語を選択（Node.js 20 / Python） |
| 4 | コードを記述 |
| 5 | 入力プロパティ・出力プロパティを設定 |
| 6 | テスト実行で動作確認 |
入力プロパティでワークフロー上の値をコードに渡し、出力プロパティで処理結果を後続のアクションに渡す、という流れを意識すると設計しやすくなります。
実装例：受注時に請求レコードを自動生成
取引が「受注」ステージに移行した際に、月額料金×契約期間分の請求カスタムオブジェクトレコードを自動生成する例です。カスタムオブジェクトを使うことで、請求管理のような業種・業態ごとの固有データをCRM内で扱えます。
// Node.js example (simplified)
const hubspot = require('@hubspot/api-client');
exports.main = async (event, callback) => {
const hubspotClient = new hubspot.Client({
accessToken: process.env.SECRET_TOKEN
});
const dealId = event.object.objectId;
const monthlyAmount = event.inputFields['monthly_amount'];
const contractMonths = event.inputFields['contract_months'];
// 契約月数分の請求レコードを作成
for (let i = 0; i < contractMonths; i++) {
const billingDate = new Date();
billingDate.setMonth(billingDate.getMonth() + i);
await hubspotClient.crm.objects.basicApi.create(
'billing_records', // カスタムオブジェクト
{
properties: {
billing_amount: monthlyAmount,
billing_date: billingDate.toISOString(),
status: 'scheduled',
deal_id: dealId
}
}
);
}
callback({ outputFields: { records_created: contractMonths } });
};この例では、受注から請求データの生成までを人手を介さずに処理しています。営業担当が請求情報を別システムに転記するような手作業を仕組みで解決できるのが、カスタムコードの価値です。
カスタムコードの制限事項
実行環境には以下の制約があります。
- 実行時間: 最大20秒
- メモリ: 128MB
- 外部ライブラリ:
@hubspot/api-client,axios,lodash等の一部のみ利用可能 - シークレット: 環境変数でAPIキー等を安全に管理
ただし、実行時間の制約上、大量レコードを1回の実行で処理するような設計には向きません。
重い処理はAPI連携側で外部に逃がすなど、処理の置き場所を分けて設計するのがポイントです。
次の図は、カスタムコードアクションを組み込んだワークフローの例（デモ）です。
カスタムコードアクションを組み込んだワークフローの例（デモ）。
HubSpot APIによる外部システム連携
HubSpotのREST APIを使うと、外部システムとデータを双方向にやり取りできます。代表的な活用例は次のとおりです。
- 基幹システム（ERP/会計ソフト） ── 受注データの同期
- 外部BIツール ── データのエクスポート
- 自社プロダクト ── ユーザー行動データのCRM同期
- 請求書発行システム ── 請求まわりの連携
主なAPIカテゴリ
| カテゴリ | 主なエンドポイント | 用途 |
|---|---|---|
| CRM API | /crm/v3/objects/contacts |
コンタクト・会社・取引のCRUD |
| CRM API | /crm/v3/objects/deals |
取引データの操作 |
| Marketing API | /marketing/v3/emails |
メール配信の管理 |
| CMS API | /cms/v3/blogs/posts |
ブログ記事の管理 |
| Automation API | /automation/v4/workflows |
ワークフローの管理 |
| Webhooks | Webhook設定 | イベントドリブンの連携 |
次の図は、HubSpotのAPIリファレンスドキュメントです。カスタムコードから呼ぶAPI仕様を確認できます。
HubSpotのAPIリファレンスドキュメント。カスタムコードから呼ぶAPI仕様を確認できます。
API認証（Private App Token）
HubSpotのAPIはPrivate App Token（旧API Key）で認証します。発行の手順は次の通りです。
- HubSpotの設定 → 統合 → Private Apps
- 新しいPrivate Appを作成
- 必要なスコープ（権限）を設定
- トークンを取得
スコープは最小限に設定するのがベストプラクティスです。全権限を付与してしまうと、トークンが漏洩した場合のリスクが大きくなります。
実装例：外部システムからのデータ同期
外部の請求管理システムからHubSpotに請求データを同期する例です。
// 外部の請求管理システムからHubSpotに請求データを同期
const axios = require('axios');
const HUBSPOT_TOKEN = 'your-private-app-token';
async function syncBillingData(externalBillingId, dealId) {
// 外部システムから請求データを取得
const billingData = await axios.get(
`https://billing-system.example.com/api/invoices/${externalBillingId}`
);
// HubSpotの取引を更新
await axios.patch(
`https://api.hubapi.com/crm/v3/objects/deals/${dealId}`,
{
properties: {
billing_status: billingData.data.status,
last_payment_date: billingData.data.lastPaymentDate
}
},
{
headers: {
Authorization: `Bearer ${HUBSPOT_TOKEN}`,
'Content-Type': 'application/json'
}
}
);
}APIレート制限とバッチAPI
HubSpotのAPIにはレート制限があります。
- Private App: 1秒あたり100リクエスト（Professional）、1秒あたり200リクエスト（Enterprise）
- バッチAPI: 1リクエストで最大100件のレコードを一括操作可能
大量データの処理にはバッチAPIの活用が必須です。1件ずつAPIを叩くと、レート制限に引っかかる上にパフォーマンスも悪化します。
同期処理を設計するときは、更新対象の件数と頻度を先に見積もっておくと安心です。
カスタムカード（UI Extensions）の概要と活用
カスタムカードは、HubSpotのレコード画面の右側パネルに独自のUIコンポーネントを表示する機能です。
HubSpot Developer Platformの一部として提供されており、営業担当がレコードを開いたまま外部情報を確認・操作できるようになります。
カスタムカードとは
レコード画面の右側パネルに表示されるカード単位のUIを、Reactベースで自作できる仕組みです。
標準のプロパティ一覧やアクティビティ履歴に加えて、外部システムの情報や独自の操作ボタンを同じ画面に並べられます。
開発環境
- フレームワーク: React ベース
- 開発ツール: HubSpot CLI（
hs-cli） - ホスティング: HubSpotのサーバーレス環境
- 言語: JavaScript/TypeScript
フロントエンド開発の経験があるエンジニアであれば取り組みやすい構成です。ただしReactベースのため、開発リソースが社内にいない場合は外部パートナーへの依頼も選択肢になります。
代表的な活用パターン
| パターン | 内容 |
|---|---|
| 外部データの表示カード | 取引レコードを開いたときに、外部の請求管理システムの支払い状況を自動表示 |
| アクションボタンカード | 「契約書を生成」「請求書を発行」ボタンで外部APIをワンクリック呼び出し |
| スコア表示カード | 独自の計算結果やスコアをビジュアル表示 |
| ミニダッシュボード | 取引レコード内に請求管理のミニダッシュボードを表示 |
例えば外部データの表示カードを使えば、営業担当が「この顧客の請求は滞っていないか」をHubSpotの画面だけで確認できます。画面を行き来する手間が省ける分、対応スピードも上がります。
標準機能・iPaaS・カスタムコードの使い分け基準
カスタムコードは強力ですが、メンテナンスコストが発生します。このセクションでは、3つの手段をどう使い分けるかの判断軸を整理します。
私たちは「標準機能でできることは標準機能で」を基本に、不足分だけをコードで補う優先順位をおすすめしています。
判断の優先順位
次の順で検討を進めるのが基本です。
- 標準機能 ── まず計算プロパティやワークフローの標準アクションで代替できないかを検討する
- iPaaS（Zapier/Yoom） ── 標準機能で対応できない場合に検討する
- カスタムコード ── さらに複雑な要件であれば検討する
標準機能で済む処理をコードで書くと、将来の改修時に開発者が必要になる分、運用負荷が上がります。
使い分けの比較表
| 手段 | 向いている処理 | 強み／注意点 |
|---|---|---|
| 標準機能（計算プロパティ・標準アクション） | 単純な条件分岐、プロパティの更新 | 強み：開発不要で保守が簡単 注意点：表現できるロジックに限界がある |
| iPaaS（Zapier/Yoom） | 「ツールAでイベント発生→ツールBにアクション」のシンプルな連携 | 強み：ノーコードで素早く構築できる 注意点：月額費用がかかる。複雑な分岐・ループ・データ加工は苦手 |
| カスタムコード | 複雑な条件分岐、ループ処理、データの加工・変換、高頻度のAPI呼び出し | 強み：自由度が高く要件に合わせられる 注意点：開発・メンテナンスコストが発生する |
iPaaSは月額費用がかかる一方で開発・メンテナンスコストは低い、カスタムコードは逆、というトレードオフを踏まえて選ぶとよいでしょう。
カスタムコードが向かないケース
率直に言うと、以下のケースではカスタムコードを避ける方が賢明です。
- 標準機能やiPaaSで実現できる処理をコード化しようとしている
- 社内にコードをメンテナンスできる体制がなく、ドキュメント化も難しい
- 実行時間20秒・メモリ128MBの制約に収まらない重い処理を想定している
- 要件が固まっておらず、仕様変更が頻繁に発生しそうな段階
とくに「とりあえずコードで書けば何でもできる」と考えて進めると、後から保守不能な仕組みになりがちです。
まず標準で組める範囲を整理してから、不足分に絞って開発する進め方をおすすめします。
カスタムコード開発の注意点とベストプラクティス
カスタムコードは一度動かせば終わりではなく、運用の中で保守し続けるものです。エラー時の挙動、テスト環境、引き継ぎの観点で、押さえておくべき注意点を整理します。
エラーハンドリングの仕組み化
ワークフロー内のカスタムコードでエラーが発生した場合、ワークフロー全体が停止します。
- エラーのハンドリング ── try-catchでエラーを受け止める
- エラー時の通知 ── 管理者へのメールを仕組み化しておく
エラーが起きたこと自体に気づけない状態が一番危険です。
サンドボックスでの事前テスト
カスタムコードの変更は、サンドボックス環境でテストしてから本番にデプロイしましょう。特にCRMデータを更新するコードは、意図しないデータ変更のリスクがあります。
レコードの作成・更新を伴う処理は、本番相当のデータ構成で検証してからリリースする流れを推奨します。
ドキュメント化とシークレット管理
カスタムコードは開発者以外には理解しにくいため、次の内容をドキュメント化しておくことが重要です。
- 何をするコードか
- なぜ必要か
- 入出力の仕様
開発者が退職した後にメンテナンスできなくなるリスクを防げます。
APIキーやトークンをコード内にハードコードせず、HubSpotのシークレット管理機能を使って環境変数として保存しましょう。
コードレビューの際にトークンが露出しないよう、最初の設計段階から分けておくことがポイントです。
導入の進め方——まず小さく始めて段階的に拡張する
カスタム開発というと大掛かりなプロジェクトを想像しがちですが、実際には小さな自動化から始めて効果を見ながら広げていくのが現実的な進め方です。ここでは、導入時の進め方と設計の視点を紹介します。
最初の一歩の選び方
まずは「受注時の請求レコード生成」のような、1つの明確な業務処理に絞ったカスタムコードから始めることをおすすめします。
効果が確認できてから、API連携やカスタムカードといった次の拡張に進む段階的なアプローチが、失敗のリスクを抑えられます。
すべてを一気に開発しようとすると、テストも運用も難しくなります。自社で効果が出そうな処理を見極めて優先順位をつけて、トライいただければなと思います。
人に頼らず引き継げる仕組みとして設計する
カスタムコードの価値は、個人のスキルではなく「仕組み」として業務を回せる点にあります。
受注処理や請求データの生成をコードとして仕組み化しておけば、担当者の入れ替わりがあっても同じ品質で業務が回り続けます。そのためには、コードだけでなく次の要素まで含めて「引き継げる形」で残すことがポイントです。
- ドキュメント
- テスト手順
- エラー時の対応フロー
仕組み化を意識した設計は、新人でも運用できる業務の土台になります。
自社に最適な設計を考える視点
拡張の方針は企業様によって最適な形が異なります。
- 基幹システムとの連携が課題なのか
- 画面の使い勝手が課題なのか
この違いで、選ぶべきパターンは変わってきます。技術ありきではなく、自社の業務フローのどこにボトルネックがあるかから設計を始めてください。
AIに任せる部分と人が決める部分を分けることが、品質の安定につながります。
よくある質問
Q1. カスタムコードを使うにはプログラミングスキルが必要ですか？
はい、Node.jsまたはPythonの基本的なプログラミングスキルが必要です。ただし、単純な外部APIの呼び出しやプロパティの計算であれば、テンプレートを参考にして実装できるレベルです。高度な開発が必要な場合は、HubSpotの開発パートナーに依頼するのも選択肢です。
Q2. ワークフローのカスタムコードはどのプランで使えますか？
カスタムコードアクションはProfessional以上のプランで利用可能です。API連携はすべてのプランで利用可能ですが、レート制限がプランによって異なります。カスタムカード（UI Extensions）はDeveloper Platformの一部で、Enterprise以上が推奨されます。
Q3. iPaaS（Zapier/Yoom）とカスタムコードの使い分けは？
iPaaSは「ツールAでイベント発生→ツールBにアクション」というシンプルな連携に向いています。複雑な条件分岐、ループ処理、データの加工・変換が必要な場合や、APIの呼び出し頻度が高い場合はカスタムコードの方が適しています。コスト面では、iPaaSは月額費用がかかりますが、開発・メンテナンスコストは低いというトレードオフがあります。
Q4. カスタムコードがエラーで停止した場合、CRMデータはどうなりますか？
ワークフロー内のカスタムコードでエラーが発生すると、ワークフロー全体が停止します。そのため、try-catchによるエラーハンドリングと管理者への通知を組み込んでおくことが重要です。サンドボックス環境で事前にテストしておけば、本番で予期せぬ停止に直面するリスクを減らせます。
Q5. HubSpotのAPIドキュメントはどこにありますか？
HubSpotの開発者ドキュメント（developers.hubspot.com）に詳細なAPIリファレンスがあります。エンドポイント別のサンプルコード、認証方法、レート制限の説明が充実しています。HubSpot Developer Communityも活発で、開発上の疑問はそこで解決できるケースが多いです。
まとめ
HubSpotのカスタムコード機能は、標準機能では対応しきれないビジネスロジックや外部連携を実現する強力な拡張手段です。ワークフロー内カスタムコード・HubSpot API・カスタムカードという3つのパターンを、自社の業務フローのどこに置くかを意識して設計することがポイントです。
押さえておきたいポイントは以下の通りです。
- まずは標準機能とiPaaSで対応できる範囲を把握し、それでも不足する部分にカスタムコードを適用するのがベストプラクティスです
- ワークフロー内カスタムコードには実行時間20秒・メモリ128MBの制約があり、API側にはレート制限があるため、処理の置き場所を分けて設計します
- エラーハンドリング・サンドボックステスト・ドキュメント化まで含めて、引き継げる仕組みとして整えることが重要です
最初の一歩として、まずは「受注時の請求レコード生成」のような1つの明確な業務処理に絞ったカスタムコードから始めてみてください。次の3ステップで進められます。
- 自社の業務フローで標準機能では表現しきれない処理を1つ洗い出す
- サンドボックス環境でカスタムコードアクションを試し、テスト実行で動作確認する
- 効果を確認した上で、API連携やカスタムカードなど次の拡張の優先順位を決める
CRMを活用した業務効率化やAIとの連携に関するご相談は、CRM特化型コンサルティングのHubSpotゴールドパートナーのStartLinkまでお気軽にお問い合わせください。
「カスタムコードで業務を自動化したい」「外部システムとのAPI連携を相談したい」——そんなお悩みをお持ちでしたら、ぜひ一度ご相談ください。
あわせて読みたい
- HubSpotワークフロー設計ガイド
- HubSpot Enterprise活用ガイド
- HubSpotアプリ連携の設計方法
- HubSpotサンドボックスの使い方を徹底解説！作成手順から
- HubSpotパーミッション設計ガイド
HubSpotの機能は定期的にアップデートされるため、最新情報はHubSpot公式サイトでご確認ください。*
記事の内容を、そのまま実務に落とし込みたい方向け
HubSpotゴールドパートナーのStartLinkが、HubSpot導入・AI活用・CRM整備・業務効率化までをまとめて支援しています。記事で気になったテーマを、そのまま相談ベースで整理できます。
次に読む
株式会社StartLinkは、事業推進に関わる「販売促進」「DXによる業務効率化（ERP/CRM/SFA/MAの導入）」などのご相談を受け付けております。 サービスのプランについてのご相談/お見積もり依頼や、ノウハウのお問い合わせについては、無料のお問い合わせページより、お気軽にご連絡くださいませ。
著者情報
