2026.10.27 業務システム

HubSpotワークフローの作り方｜登録トリガー・再登録・カスタムコードの実装と落とし穴【2026年10月】

HubSpotのワークフローは、条件を満たしたコンタクトや取引を自動で登録し、メール送信・担当者の割り当て・プロパティ更新などを順に実行する機能です。つまずくのは画面の操作ではなく、同じレコードを何度登録させるかを決める「再登録」と、外部のシステムを呼ぶ部分です。この記事では2026年10月時点の公式ドキュメントをもとに、作成手順と4種類の登録トリガー、二重送信を招く再登録の判定規則、外部APIを呼ぶカスタムコードのNode.js例、Webhook送信との使い分け、Workflows APIでのバックアップまでをコード付きで示します。

まとめ：HubSpotワークフローは再登録の条件と外部連携の切り分けで決まる

ワークフローを使えるのは、Marketing Hub・Sales Hub・Service Hub・Data HubなどのProfessional以上の契約です。作成上限はProfessionalで300件、Enterpriseで1,000件あります。登録トリガーはフィルター・イベント・スケジュール・Webhookの4種類から選び、公開時には「今条件を満たしている既存レコードを登録するか」を必ず決めます。

再登録は、条件が「満たさない状態から満たす状態へ変わった」ときだけ起き、再登録されたレコードは最初のアクションからやり直します。メールの二重送信が生まれる原因は、この最初からのやり直しです。外部システムとの連携は、通知だけならWebhook送信アクション、データの変換や応答の判定が要るならカスタムコードアクションで組みます。カスタムコードは20秒以内に終える必要があり、失敗すると最大3日間再試行されるため、送り先は二重に受けても壊れない作りにしておきます。

HubSpotワークフローを使う前提：対象の契約・作成上限・クレジット消費の確認

設計に入る前に、自社の契約で何件まで作れ、どのアクションが使えるかを確かめます。

Professional以上で使える契約と作成上限300件・1,000件の数え方

ワークフロー作成の公式ヘルプが対象に挙げるのは、Marketing Hub・Sales Hub・Service Hub・Data Hub・Smart CRM・Revenue HubのProfessionalとEnterpriseです。作れる件数はワークフローのよくある質問（公式）に契約ごとに書かれています。

契約するHub	Professional	Enterprise
Marketing／Sales／Service	300件	1,000件
Data Hub	400件	1,100件
Brandsアドオン	100件を追加	100件を追加

複数のHubを契約している場合は、上限が最も大きい契約の値が使われます。Marketing Hub ProfessionalとSales Hub Enterpriseの組み合わせなら1,000件です。1つのワークフローに付けられる登録トリガーは250個までで、それを超えるならワークフローを分けます。Hubごとの機能差と料金はHubSpotの料金｜7つのHubの構造とシート・コンタクト二層課金の決まり方で整理しています。

AIアクションのクレジット消費と、作成上限に数えない簡易ワークフロー

上限に数えるのは、ワークフローのツールで作ったものだけです。フォーム・メール・広告の各ツールで作る簡易ワークフロー、パイプライン設定の自動化、シーケンスは数えません。

もう1つ見落としやすいのが費用です。レコードの要約やData Agentのような、ワークフロー内のAI系のアクションとトリガーはHubSpotクレジットを消費します。HubSpotの製品・サービスカタログでは、ワークフローでAIアクションを1回実行すると10クレジットです。1日1,000件のレコードが通るワークフローにAIアクションを1つ置けば、1日1万クレジットになります。登録件数を見積もってから置き場所を決めてください。

作成手順：ゼロから作り、登録トリガーを設定し、既存レコードの扱いを決めて公開

メニューの「自動化」から「ワークフロー」を開き、右上の「ワークフローを作成」から始めます。

ゼロから・テンプレート・Breeze Assistantの作り始め方と向く場面

作り始め方は、ゼロから作る、Breeze Assistant（HubSpotのAI）に指示して作る、テンプレートから作るの3通りです。AIに頼む場合、公式ヘルプは「〇〇が起きたら、〇〇をする」の形で指示を書くよう勧めています。

実装の担当者が組むなら、ゼロから作るのが確実です。AIやテンプレートで作った下書きも、登録トリガーと再登録の設定は必ず開いて読み直します。

フィルター・イベント・スケジュール・Webhookの4種類の登録トリガー

登録トリガーは、レコードを自動でワークフローに入れる条件です。自動で入れずに、担当者が手で登録する運用も選べます。

種類	登録するタイミング	向く処理の例
フィルター	プロパティが条件に合ったとき	ライフサイクルの変更
イベント	フォーム送信などが起きたとき	資料請求後のメール
スケジュール	決めた日時や周期	毎月の契約更新の確認
Webhook	外部からの通知を受けたとき	基幹システムの出荷連絡

対象のオブジェクト（コンタクト・会社・取引・チケットなど）は、トリガーと一緒に選びます。決め方は「誰に対して」アクションを実行したいかです。取引の受注を起点に担当者へタスクを作るなら取引、フォーム送信者にメールを送るならコンタクトを選びます。再登録に使えるのも同じ種類のオブジェクトのプロパティに限られるため、ここで選んだオブジェクトが後の設計の範囲を決めます。

公開時に既存レコードを登録するかの選択と、一括登録を10分ずつずらす手順

右上の公開ボタン（Review and publish）を押すと、今条件を満たしている既存レコードを登録するかを聞かれます。「はい」を選ぶと、今の時点で条件を満たすレコードがまとめて入り、1通目のメールが一斉に送られます。新しい問い合わせだけを対象にしたいなら「いいえ」です。

確認画面で、登録対象になる既存レコードの件数を見る（表示は概算）
正確な件数が必要なら、確認画面のリンク（See all contacts in lists）から静的リストを作る
既存レコードを入れる場合は、リストを数千件ずつに分ける
1つ目のまとまりを手動で登録し、10分空けて次を登録する

公式のよくある質問によると、大量の一括登録は同じアカウントの他のワークフローまで遅らせます。10分ずらすのはそのためです。

再登録と分岐の設計：同じメールの二重送信と登録漏れを起こさない条件の組み方

既定では、レコードがワークフローに入るのは最初に条件を満たしたときの1回だけです。2回目以降も入れたいときに再登録を使います。

再登録が起きるのは不一致から一致へ変わった時だけという判定規則

再登録トリガーの公式ヘルプが定める規則のうち、設計に効くのは次の6つです。

再登録は、最初の登録条件を満たし、かつ選んだ再登録トリガーが「満たさない」から「満たす」へ変わったときに起きる
再登録トリガーはOR条件だけで、AND条件は組めない
使えるのはワークフローと同じ種類のオブジェクトのプロパティで、活動とそのプロパティは使えない
ワークフローの途中にいるレコードは再登録されず、終わるか外れた後に再登録される
再登録されたレコードは最初からやり直し、自動メールも再び送られる
登録トリガーに付けた期間や回数の絞り込みは、再登録には効かない

最後の規則は見落とされがちです。「1月中にフォームを送信した人」を登録条件にしても、再登録を有効にすると期間外の送信で入り直します。

「is known」の条件でライフサイクルステージの変更ごとに再送される失敗例

よくある事故は、「ライフサイクルステージが既知（is known）」を再登録トリガーにする設定です。公式ヘルプによると、is knownは値が入ったときだけでなく、値が別の値に変わるたびに再登録の対象になります。リードから顧客へ、顧客からエバンジェリストへと変わるたびに、ウェルカムメールが最初から送り直されます。

再登録のトリガーには、「ライフサイクルステージが〇〇に等しい」のように特定の値を指定します。日付の条件にも注意が要ります。最終更新日の is known は再登録に使えず、「今日」を再登録トリガーにすることも公式は勧めていません。周期的に処理したいならスケジュールのトリガーにします。稼働中のワークフローで再登録を有効にして保存するときは、既存のレコードを登録しない保存（Save and don’t enroll existing contacts）を選び、過去分の再送を防ぎます。

1つのプロパティで最大250本の分岐と、分析系の条件の前に置く80分の遅延

分岐の公式ヘルプによると、1つのプロパティの値や前のアクションの結果で分ける分岐は、1回で最大250本まで作れます。この方式ではAND・ORの条件を組めないので、複数の条件を組み合わせるならAND/OR型の分岐を使います。割合で無作為に分ける分岐はMarketing Hub Professional以上が必要で、ほぼ均等に分かれるのは1,000件以上が通る場合です。

ページビューのような分析データで分岐するなら、直前に80分の遅延を置きます。反映を待たずに判定すると、閲覧した人が「未閲覧」の枝に流れます。

カスタムコードアクションで外部APIを呼ぶ：Node.jsの実装と20秒の制約

標準のアクションで足りない処理は、ワークフローの中でJavaScriptかPythonを動かすカスタムコードアクションで書きます。

Data Hub Pro以上で使うシークレットと入力プロパティの渡し方

カスタムコードアクションの公式ガイドによると、この機能にはData Hub ProfessionalかEnterpriseの契約が要ります。コードはHubSpotが管理するAWS Lambda上で動き、Node.jsではaxiosや@hubspot/api-clientなどの決まったライブラリだけを読み込めます。

外部APIのトークンは、コードに書かずに「シークレット」に登録します。シークレットは環境変数としてprocess.env.シークレット名で読め、1つのアクションで使うシークレットの値は合計1,000字以内です。レコードの値は「コードに含めるプロパティ」で最大50個まで渡せ、event.inputFieldsで読めます。APIでレコードを取り直さずに済むので、呼び出し回数の上限にも響きません。

受注した取引を基幹システムへ送るNode.jsのカスタムコード例

次の例は、取引ベースのワークフローで、取引が受注になったら金額と顧客コードを基幹システムの受注APIへ送ります。プロパティにamountとerp_customer_code、シークレットにERP_API_TOKEN、データ出力に文字列型のerp_statusとerp_order_idを設定してから貼り付けます。

const axios = require('axios');

exports.main = async (event, callback) => {
  const dealId = String(event.object.objectId);
  const customerCode = event.inputFields['erp_customer_code'];
  const amount = Number(event.inputFields['amount'] || 0);

  if (!customerCode) {
    // 顧客コードが無い取引は送らず、後ろの分岐で担当者に知らせる
    callback({ outputFields: { erp_status: 'no_customer_code', erp_order_id: '' } });
    return;
  }

  try {
    const res = await axios.post(
      'https://erp.example.co.jp/api/orders',
      { customerCode, amount, sourceDealId: dealId },
      {
        headers: {
          Authorization: `Bearer ${process.env.ERP_API_TOKEN}`,
          'Idempotency-Key': `hubspot-deal-${dealId}`, // 再試行で同じ取引を二重に登録させない
        },
        timeout: 15000, // 20秒の上限より前に打ち切る
      }
    );
    callback({ outputFields: { erp_status: 'sent', erp_order_id: String(res.data.orderId) } });
  } catch (err) {
    const status = err.response ? err.response.status : 0;
    if (status === 429 || status >= 500) {
      throw err; // HubSpotに再試行させる
    }
    callback({ outputFields: { erp_status: `error_${status}`, erp_order_id: '' } });
  }
};

出力したerp_statusは、後ろの分岐の条件や、レコードを編集するアクション（Edit records）の値に使えます。sent以外の枝で担当者へタスクを作れば、送れなかった取引を人が拾えます。アクション画面のテスト（Test action）は選んだ実在のレコードで本当に実行されるため、テスト用の取引を作ってから試してください。

最大3日間の自動再試行を前提にした冪等キーと20秒・128MBの制約

公式ガイドの制限は、実行時間20秒、メモリ128MBです。超えるとエラーで止まります。axiosか@hubspot/api-clientで429か5xxを受けて例外を投げると、HubSpotは1分後から最大3日間、間隔を延ばしながら（最大8時間空けて）アクションをやり直します。

この再試行が二重登録を招きます。基幹システムが受注を保存した直後に5xxを返すと、同じ取引がもう一度届くからです。上のコードは取引IDから作ったIdempotency-Keyを付け、2回目を送り先で捨てられるようにしています。受け側の作り方は冪等キーとは？Idempotency-Keyの発行・保存・再生の実装と二重課金の止め方を解説で扱っています。

Node.jsでは、exports.mainの外で宣言した変数が次の実行に持ち越されることがあります。実行ごとに変わる値は、必ず関数の中で宣言する必要があります。Math.randomは同時に登録された複数の実行で同じ値になりうるため、担当者の無作為な割り当てに使うのは、公式が勧めるrandom-number-csprngです。HubSpotのAPIをコードから呼ぶ場合のトークンと上限は、HubSpot APIの使い方｜認証の選び方とupsert・Webhook・レート制限の実装を参照してください。

Webhook送信アクションとの使い分け：コードを書かずに外部へ通知できる範囲

外部へデータを送るだけなら、コードを書かないWebhook送信のアクション（Send a webhook）でも組めます。

Send a webhookのHTTPS必須・2種類の認証と4xxで止まる再送の規則

ワークフローでWebhookを使う公式ヘルプによると、このアクションもData Hub ProfessionalかEnterpriseで使え、POSTでHubSpotのデータを送るか、GETで外部のデータを取り込みます。URLはHTTPSで始まる必要があり、認証はリクエスト署名をヘッダに付けるか、APIキーを付けるかを選びます。

再送の規則は、受け側の設計に直結します。失敗したWebhookの再送は、1分後から最大3日間、間隔を延ばして（最大8時間空けて）行われる仕組みです。4xxを返すと再送されませんが、429だけは例外で、Retry-Afterヘッダがあればその値（ミリ秒）に従って再送されます。受け側で署名を検証し、同じ通知を2回受けても結果が変わらない作りにする方法はWebhookの作り方と実装方法｜受信側の署名検証・冪等性と送信側の再送をNode.js・Pythonで解説にまとめています。

Webhookで足りる処理とカスタムコードに切り替える判断の目安

判断の基準は、送る前と受けた後に「判定」が要るかどうかです。

要件	Webhook送信	カスタムコード
プロパティをそのまま送る	足りる	過剰
送る前に値を変換・結合する	難しい	向く
応答の中身で分岐する	出力の項目で可	向く
2つ以上のAPIを順に呼ぶ	不可	向く
保守する人がコードを読めない	向く	避ける

まずWebhook送信で組み、変換や複数の呼び出しが要る箇所だけをカスタムコードに置き換えると、保守の手間が最も少なく済みます。どちらのアクションにもレート制限を設定でき、送り先の上限に合わせて実行回数を絞れます。

Workflows API（v4ベータ）で全ワークフローの定義をJSONに書き出す手順

ワークフローが100件を超えると、誰が何を変えたかを画面で追えなくなります。定義をJSONで書き出せば、差分で確かめられます。

automationスコープのトークンで一覧と定義を取得するPythonコード

Workflows APIの公式ガイドによると、v4のエンドポイントにはautomationスコープが要ります。GET /automation/v4/flowsはIDや有効・無効などの主要項目だけを返すため、全体の定義の取得に使うのは1件ずつ呼ぶGET /automation/v4/flows/{flowId}です。次のコードはpip install requestsだけで動きます。

import json
import os
import pathlib
import time

import requests

TOKEN = os.environ["HUBSPOT_TOKEN"]  # automationスコープを付けた非公開アプリのトークン
BASE = "https://api.hubapi.com/automation/v4/flows"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}
OUT = pathlib.Path("workflow_backup")
OUT.mkdir(exist_ok=True)


def list_flow_ids():
    """一覧からワークフローIDを集める（続きのページがあれば after で辿る）"""
    ids, after = [], None
    while True:
        params = {"after": after} if after else {}
        res = requests.get(BASE, headers=HEADERS, params=params, timeout=30)
        res.raise_for_status()
        body = res.json()
        ids += [flow["id"] for flow in body.get("results", [])]
        after = body.get("paging", {}).get("next", {}).get("after")
        if not after:
            return ids


for flow_id in list_flow_ids():
    res = requests.get(f"{BASE}/{flow_id}", headers=HEADERS, timeout=30)
    res.raise_for_status()
    flow = res.json()
    path = OUT / f"{flow_id}_rev{flow.get('revisionId')}.json"
    path.write_text(json.dumps(flow, ensure_ascii=False, indent=2), encoding="utf-8")
    print(flow_id, flow.get("name"), "有効" if flow.get("isEnabled") else "停止中")
    time.sleep(0.1)  # 10秒あたりの呼び出し上限に余裕を残す

ファイル名にrevisionIdを入れているので、Gitに保存すれば前の版と比べられます。定義の中のenrollmentCriteria.shouldReEnrollを見れば、再登録が有効なワークフローを洗い出せます。

更新にrevisionIdが必須で、削除はAPIから復元できないベータ版の注意

v4はベータ版で、仕様が変わる可能性があると公式に書かれています。更新には最新のrevisionIdとtypeが必須で、送らなかったアクションはワークフローから消えます。APIで削除したワークフローはAPIから復元できず、HubSpotのサポートに頼むしかありません。

このため、APIは読み取りとバックアップに限り、変更は画面で行う運用を勧めます。APIでの作成は、同じ形のワークフローを数十の事業部に配るような規模になってからで十分です。

受託開発の視点で見る、ワークフローで組む処理と外部開発へ切り出す処理の境界

ここからは、HubSpotと基幹システムの連携を受ける立場からの判断です。

ワークフローで完結させる処理：通知・担当者の割り当て・プロパティ更新

HubSpotの中で閉じる処理は、ワークフローで組みます。具体的な対象は、フォーム送信者へのメール、担当者の割り当てとタスク作成、ライフサイクルステージの更新、社内通知です。マーケティングや営業の担当者が自分で直せる形にしておけば、条件の変更のたびに開発を頼まずに済みます。

外部への連携も、1つのシステムへプロパティを送るだけならWebhook送信で足ります。送り先が複数のSaaSにまたがり、画面で組みたいならiPaaSも選択肢です。料金の数え方はiPaaSとは？仕組み・RPAとの違い・料金の数え方と導入判断をわかりやすく解説で確認してください。

外部開発へ切り出す条件：20秒を超える処理・複数システムの整合・監査

次のどれかに当てはまるなら、カスタムコードに詰め込まず、外部のサーバーで処理を組みます。1件の処理が20秒を超えうるとき（大きなファイルの生成や、応答の遅い基幹システムの呼び出し）。受注と在庫と請求のように、複数のシステムの更新をそろって成功させる必要があるとき。誰がいつどのデータを送ったかを、90日より長く監査用に残す必要があるときです。公式のよくある質問によると、ワークフローのアクションログは90日、登録の履歴は6か月で消えます。

この場合は、ワークフローからWebhookで外部のサーバーへ通知だけを送り、重い処理と記録は外部側で持つ形にします。HubSpotの設定とその先の連携開発をまとめて頼みたい場合は、HubSpot導入支援サービスで要件の整理から受け付けています。

HubSpotワークフローのよくある質問：無料版・履歴の保存期間・Python対応

ワークフローを組む前によく寄せられる質問に、2026年10月時点の公式ヘルプと開発者ドキュメントをもとに回答します。

HubSpotの無料版やStarterでもワークフローは使えますか？

ワークフローのツールは、公式ヘルプが対象とするProfessionalとEnterpriseの契約で使えます。無料版とStarterは対象に入っていません。ただし、フォームやマーケティングメールのツールから作る簡易ワークフローは別の機能で、作成上限にも数えません。自社の契約で使える範囲は、ワークフローの作成画面で鍵のアイコンが付いたアクションがないかで確かめられます。

稼働中のワークフローにアクションを足すと、登録中のレコードはどうなりますか？

まだ新しいアクションの位置まで進んでいないレコードは、そこに着いた時点で実行されます。すでにその位置を過ぎたレコードは、新しいアクションを実行しません。過ぎたレコードにも実行させたいなら、新しいアクションだけを持つ別のワークフローを作るのが安全です。

ワークフローの実行履歴はどれくらいの期間残りますか？

公式のよくある質問では、アクションログは90日、登録の履歴は6か月保存されます。成功したアクションのログは1日10万件までで、超えるとその日の成功ログは残りませんが、エラーのログは残り続けます。90日を超えて確かめたい処理は、外部のログやHubSpotのプロパティに実行結果を書き残してください。

削除して復元したレコードをワークフローに戻せますか？

削除されたレコードはワークフローから自動で外れ、遅延の途中で削除して復元しても、続きからは再開しません。戻すには再登録を有効にしたうえで、そのレコードを手動で登録します。最初のアクションからやり直すため、メールを送るワークフローでは送り直しになる点に注意が必要です。

カスタムコードはPythonでも書けますか？

書けますが、2026年10月時点のPythonはベータ版で、コード欄に構文エラーの表示が出ません。公式ガイドは、Python 3.9のカスタムコードを2027年1月5日以降は作成・更新できなくなると告知しており、3.14への切り替えを勧めています。既存のアクションは動き続けますが、修正できなくなる前に移してください。