「HubSpotの標準機能だけでは、自社固有のビジネスロジックを実装できない」
「外部システムとの連携を自動化したいが、iPaaSでは対応しきれない」
——こうしたケースでは、カスタムコードによるCRM拡張が有力な選択肢になります。
HubSpotのカスタムコード機能とは、ワークフロー内でNode.jsやPythonのコードを実行したり、APIを使って外部システムと連携したり、レコード画面にカスタムカード（UI Extensions）を追加したりできる開発者向けの拡張機能のことです。
この記事では、カスタムコードの3つの活用パターンと、それぞれの実装方法、設計上の注意点を解説します。
ワークフローの中で、標準アクションでは実現できない処理をNode.jsまたはPythonで実装します。Professional以上のプランで利用可能です。
活用例:
HubSpotのREST APIを使って、外部システムとデータを双方向にやり取りします。
活用例:
HubSpotのレコード画面（コンタクト・会社・取引等）に、独自のUIコンポーネントを追加します。
活用例:
取引が「受注」ステージに移行した際に、月額料金×契約期間分の請求カスタムオブジェクトレコードを自動生成する例です。
// 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 } });
};@hubspot/api-client, axios, lodash等の一部のみ利用可能| カテゴリ | 主なエンドポイント | 用途 |
|---|---|---|
| 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はPrivate App Token（旧API Key）で認証します。
スコープは最小限に設定するのがベストプラクティスです。全権限を付与してしまうと、トークンが漏洩した場合のリスクが大きくなります。
// 外部の請求管理システムから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'
}
}
);
}HubSpotのAPIにはレート制限があります。
大量データの処理にはバッチAPIの活用が必須です。1件ずつAPIを叩くと、レート制限に引っかかる上にパフォーマンスも悪化します。
カスタムカードは、HubSpotのレコード画面の右側パネルに独自のUIコンポーネントを表示する機能です。HubSpot Developer Platformの一部として提供されています。
hs-cli）外部データの表示カード
取引レコードを開いたときに、外部の請求管理システムの支払い状況を自動表示。営業担当が「この顧客の請求は滞っていないか」をHubSpotの画面だけで確認できます。
アクションボタンカード
「契約書を生成」「請求書を発行」といったボタンを配置し、ワンクリックで外部APIを呼び出し。画面を行き来する手間が省けます。
カスタムコードは強力ですが、メンテナンスコストが発生します。まず計算プロパティ・ワークフローの標準アクション・iPaaS（Zapier/Yoom）で代替できないか検討し、それでも対応できない場合にカスタムコードを使うという優先順位が重要です。
ワークフロー内のカスタムコードでエラーが発生した場合、ワークフロー全体が停止します。try-catchでエラーをハンドリングし、エラー時の通知（管理者へのメール）を仕組み化しておきましょう。
カスタムコードの変更は、必ずサンドボックス環境でテストしてから本番にデプロイしましょう。特にCRMデータを更新するコードは、意図しないデータ変更のリスクがあります。
カスタムコードは開発者以外には理解しにくいため、何をするコードか・なぜ必要か・入出力の仕様をドキュメント化しておくことが重要です。開発者が退職した後にメンテナンスできなくなるリスクを防ぎます。
APIキーやトークンをコード内にハードコードせず、HubSpotのシークレット管理機能を使って環境変数として保存しましょう。
HubSpotのカスタムコード機能は、標準機能では対応しきれないビジネスロジックや外部連携を実現する強力な拡張手段です。
まずは標準機能とiPaaSで対応できる範囲を把握し、それでも不足する部分にカスタムコードを適用するのがベストプラクティスです。ワークフロー内カスタムコードで業務ロジックの自動化から始め、必要に応じてAPI連携やカスタムカードに拡張していきましょう。
StartLinkでは、HubSpotの導入設計からカスタム開発まで、企業様の状況に合わせた支援を行っています。
「カスタムコードで業務を自動化したい」「外部システムとのAPI連携を相談したい」——そんなお悩みをお持ちでしたら、ぜひ一度ご相談ください。
はい、Node.jsまたはPythonの基本的なプログラミングスキルが必要です。ただし、単純な外部APIの呼び出しやプロパティの計算であれば、テンプレートを参考にして実装できるレベルです。高度な開発が必要な場合は、HubSpotの開発パートナーに依頼するのも選択肢です。
カスタムコードアクションはProfessional以上のプランで利用可能です。API連携はすべてのプランで利用可能ですが、レート制限がプランによって異なります。カスタムカード（UI Extensions）はDeveloper Platformの一部で、Enterprise以上が推奨されます。
iPaaSは「ツールAでイベント発生→ツールBにアクション」というシンプルな連携に向いています。複雑な条件分岐、ループ処理、データの加工・変換が必要な場合や、APIの呼び出し頻度が高い場合はカスタムコードの方が適しています。コスト面では、iPaaSは月額費用がかかりますが、開発・メンテナンスコストは低いというトレードオフがあります。
HubSpotの開発者ドキュメント（developers.hubspot.com）に詳細なAPIリファレンスがあります。エンドポイント別のサンプルコード、認証方法、レート制限の説明が充実しています。HubSpot Developer Communityも活発で、開発上の疑問はそこで解決できるケースが多いです。
この記事は2025年3月時点の情報に基づいています。HubSpotの機能は定期的にアップデートされるため、最新情報はHubSpot公式サイトでご確認ください。
関連記事: