Contents
スポンサードリンク
1. HubSpot プライベートアプリと OAuth の基礎
1‑1．プライベートアプリ作成とスコープ設定
| 手順 | 操作画面のポイント |
|---|---|
| ① HubSpot にログイン → Settings（設定） → Integrations（統合） → Private Apps（プライベートアプリ） | 「Create private app」ボタンが左上にあります。 |
| ② アプリ名・説明を入力し、Scopes（権限） を選択 | 必要な API に応じて以下のスコープを最低でも付与してください。 • contacts （コンタクト操作）• forms （フォーム取得/送信）• content （CMS コンテンツ）※ スコープはスペース区切りで列挙し、URL エンコードが必要です。 |
| ③ Redirect URL を登録 | 「OAuth redirect URIs」欄に WordPress 側の受信用エンドポイント（例: https://example.com/oauth/hubspot/callback）を必ず追加してください。HubSpot はこのリスト以外へのリダイレクトを拒否します。 |
| ④ Create をクリック → 発行された Client ID と Client Secret をメモ | 後続の認可 URL 作成とトークン取得で必須です。 |
ポイント：スコープは URL エンコード が必要です。例えば
contacts formsはcontacts%20formsとなります。
1‑2．OAuth 認可リクエスト（ユーザー認証画面への誘導）
|
1 2 3 4 5 6 |
https://app.hubspot.com/oauth/authorize? client_id=YOUR_CLIENT_ID& scope=contacts%20forms%20content& redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fhubspot%2Fcallback& response_type=code |
| パラメータ | 説明 |
|---|---|
client_id |
プライベートアプリ作成時に取得した Client ID |
scope |
スペースで区切ったスコープを URL エンコード（例: contacts%20forms） |
redirect_uri |
事前登録したリダイレクト先。必ずエンコードすること |
response_type=code |
認可コード取得を指示 |
ユーザーが HubSpot にログインし、スコープへの同意を行うと リダイレクト URI に以下のように認可コードが付与されます。
|
1 2 |
https://example.com/oauth/hubspot/callback?code=AUTHORIZATION_CODE |
1‑3．アクセストークン取得（Authorization Code の交換）
|
1 2 3 4 5 6 7 |
curl -X POST https://api.hubapi.com/oauth/v1/token \ -d "grant_type=authorization_code" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" \ -d "redirect_uri=https://example.com/oauth/hubspot/callback" \ -d "code=AUTHORIZATION_CODE" |
レスポンス例（JSON）
|
1 2 3 4 5 6 7 |
{ "access_token": "xxxxxxxxxxxx", "refresh_token": "yyyyyyyyyyyy", "expires_in": 21600, "token_type": "bearer" } |
注意：
hapikeyは OAuth フローでは使用できません。上記のようにclient_id / client_secretとgrant_type=authorization_codeを必ず送信してください。
2. アクセストークンの有効期限と自動リフレッシュ（PHP 実装）
HubSpot のアクセストークンは 6 時間（デフォルト）で失効します。リフレッシュトークンは最大 30 日間 有効です。以下のコードは、WordPress の Cron と wp_remote_post を組み合わせて自動更新するサンプルです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 |
<?php // functions.php もしくは独自プラグインに追加 /** * HubSpot アクセストークンをリフレッシュし、WP オプションに保存する。 * * @return string|false 新しいアクセストークン、失敗時は false */ function hubspot_refresh_access_token() { $refresh_token = getenv('HUBSPOT_REFRESH_TOKEN'); // .env から取得 $response = wp_remote_post( 'https://api.hubapi.com/oauth/v1/token', [ 'body' => [ 'grant_type' => 'refresh_token', 'client_id' => getenv('HUBSPOT_CLIENT_ID'), 'client_secret' => getenv('HUBSPOT_CLIENT_SECRET'), 'refresh_token' => $refresh_token, ], 'timeout' => 15, ]); if ( is_wp_error( $response ) ) { error_log( '[HubSpot] Token refresh failed: ' . $response->get_error_message() ); return false; } $data = json_decode( wp_remote_retrieve_body( $response ), true ); if ( empty( $data['access_token'] ) ) { error_log( '[HubSpot] Unexpected token response: ' . wp_remote_retrieve_body( $response ) ); return false; } // 新しいトークンを安全に保存（WP オプションは自動的にシリアライズされるので OK） update_option( 'hubspot_access_token', $data['access_token'] ); // 必要ならリフレッシュトークンも更新 if ( ! empty( $data['refresh_token'] ) ) { putenv( "HUBSPOT_REFRESH_TOKEN={$data['refresh_token']}" ); } return $data['access_token']; } /** * 1時間ごとにアクセストークンを自動更新する WP‑Cron イベント登録 */ function hubspot_schedule_token_refresh() { if ( ! wp_next_scheduled( 'hubspot_hourly_token_refresh' ) ) { wp_schedule_event( time(), 'hourly', 'hubspot_hourly_token_refresh' ); } } add_action( 'wp', 'hubspot_schedule_token_refresh' ); add_action( 'hubspot_hourly_token_refresh', 'hubspot_refresh_access_token' ); |
ポイント：トークンは
update_option()でデータベースに保存し、get_option('hubspot_access_token')から取得すればコード全体で一元管理できます。
3. 公式プラグイン「HubSpot All‑In‑One Marketing」でのノーコード接続
3‑1．プラグインのインストールと有効化手順
| 手順 | 操作詳細 |
|---|---|
| ① WordPress 管理画面 → Plugins（プラグイン） → Add New（新規追加） | 検索ボックスに HubSpot All‑In‑One Marketing と入力 |
| ② 「HubSpot All‑In‑One Marketing」 (開発元: HubSpot) を Install Now → Activate | インストール後、左メニューに HubSpot が追加されます |
| ③ メニュー > HubSpot → Settings（設定） に遷移 | 「Connection method（接続方法）」で OAuth token を選択 |
| ④ 取得した access_token（または refresh_token）を貼り付けて Save | 保存と同時にプラグインがトークンの有効性を検証します |
3‑2．自動的に挿入されるトラッキングコードの確認方法
- 任意のページを表示し、ブラウザの開発者ツールで Elements タブを開く。
<head>内に次のスクリプトが存在するか確認します。
|
1 2 |
<script id="hs-script-loader" async defer src="//js.hs-scripts.com/YOUR_HUB_ID.js"></script> |
- HubSpot の管理画面 → Reports（レポート） → Tracking Code で「Recent events」（直近の訪問者）が増えていれば正常に計測されています。
ポイント：プラグインは
wp_headフックを利用して必ず<head>にコードを挿入するため、テーマ更新やキャッシュが原因で抜け落ちるリスクがありません。
4. カスタム PHP から HubSpot API を呼び出す実装例
4‑1．コンタクト作成（v3 API 推奨）
HubSpot の最新 API（v3）ではプロパティは name と value のオブジェクト配列で渡します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
/** * HubSpot に新規コンタクトを作成する。 * * @param string $email メールアドレス (必須) * @param string $firstName 名（任意） * @param string $lastName 姓（任意） * @return bool|array 成功時は API の応答配列、失敗時は false */ function hubspot_create_contact_v3( $email, $firstName = '', $lastName = '' ) { $access_token = get_option( 'hubspot_access_token' ); $body = [ 'properties' => [ [ 'property' => 'email', 'value' => $email ], [ 'property' => 'firstname', 'value' => $firstName ], [ 'property' => 'lastname', 'value' => $lastName ], ] ]; $response = wp_remote_post( 'https://api.hubapi.com/crm/v3/objects/contacts', [ 'headers' => [ 'Authorization' => 'Bearer ' . $access_token, 'Content-Type' => 'application/json', ], 'body' => wp_json_encode( $body ), 'timeout' => 15, ]); if ( is_wp_error( $response ) ) { error_log( '[HubSpot] Contact create failed: ' . $response->get_error_message() ); return false; } $code = wp_remote_retrieve_response_code( $response ); // 201 Created が正常 if ( $code === 201 ) { return json_decode( wp_remote_retrieve_body( $response ), true ); } error_log( '[HubSpot] Unexpected response code: ' . $code ); return false; } |
呼び出し例
add_action('user_register', function($user_id){ ... });のように WordPress ユーザー登録フックで実行すると、会員情報が自動的に HubSpot に同期できます。
4‑2．フォーム送信データ取得（最新エンドポイント）
HubSpot Forms API（v3）では以下の URL が使用されます。hapikey は不要です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
/** * 指定した Form の送信データを取得する。 * * @param string $portal_id HubSpot ポータル ID * @param string $form_guid フォーム GUID（例: a1b2c3d4-...） * @param int $limit 取得件数上限（最大 100） * @return array|false データ配列、失敗時は false */ function hubspot_get_form_submissions( $portal_id, $form_guid, $limit = 20 ) { $access_token = get_option( 'hubspot_access_token' ); $url = add_query_arg( [ 'limit' => $limit, ], "https://api.hubapi.com/marketing/v3/forms/$form_guid/submissions" ); $response = wp_remote_get( $url, [ 'headers' => [ 'Authorization' => 'Bearer ' . $access_token, 'Accept' => 'application/json', ], 'timeout' => 15, ]); if ( is_wp_error( $response ) ) { error_log( '[HubSpot] Form submissions fetch error: ' . $response->get_error_message() ); return false; } $code = wp_remote_retrieve_response_code( $response ); if ( $code !== 200 ) { error_log( "[HubSpot] Unexpected status {$code} when fetching form submissions" ); return false; } return json_decode( wp_remote_retrieve_body( $response ), true ); } |
ポイント：取得したデータは
resultsキー配下に配列で格納され、各送信項目はvaluesオブジェクトとしてアクセスできます。
5. ノーコードツールによる双方向自動化
5‑1．HubSpot → WordPress（新規コンタクトをカスタム投稿に変換）
Zapier 手順
| ステップ | 操作内容 |
|---|---|
| Trigger | HubSpot アプリ > New Contact を選択。OAuth 認証でプライベートアプリのトークンを自動取得。 |
| Action | Webhooks by Zapier → POST リクエスト送信。URL: https://example.com/wp-json/wp/v2/posts（WordPress REST API）。 |
| Headers | Authorization: Basic BASE64(username:application_password) （WordPress のアプリケーションパスワード） |
| Body (JSON) | json { "title": "{{email}}", "content": "First name: {{firstname}}\nLast name: {{lastname}}", "status": "publish", "categories": [2] } |
| Test | Zapier のテスト実行で WordPress に投稿が作成されれば完了。 |
Make.com 手順
- Scenario 作成 → HubSpot モジュール > Watch Contacts を設定。
- 次に HTTP モジュールで
POST https://example.com/wp-json/wp/v2/postsを呼び出す。認証は同様に Basic 認証か JWT でも可。 - データマッピング画面で HubSpot のプロパティ → WordPress のフィールドを紐付け、Run once で動作確認。
5‑2．WordPress フォーム → HubSpot（リード自動送信）
| プラグイン | 主な設定ポイント |
|---|---|
| Contact Form 7 + Webhook | メール (2) の「送信先 URL」に Zapier/Make.com が提供する https://hooks.zapier.com/... を入力し、json 形式でフィールドを列挙。 |
| WPForms + Webhooks アドオン | 「Webhooks」タブ → エンドポイント URL に同様に設定。送信データは自動的に JSON 化されます。 |
Zapier 側では Catch Hook トリガー → HubSpot の Create or Update Contact アクションを選択し、マッピングすれば完了です。
注意：Webhook 経由で受け取るデータは必ずサニタイズし、WordPress 側のエンドポイントは認証（Basic 認証や IP 制限）を施してください。
6. トークン・シークレットの安全な保管方法
6‑1．.env と wp-config.php の連携（推奨）
|
1 2 3 4 5 6 7 8 9 10 11 |
// wp-config.php の末尾に追加 if ( file_exists( __DIR__ . '/.env' ) ) { $dotenv = Dotenv\Dotenv::createImmutable( __DIR__ ); $dotenv->load(); } define( 'HUBSPOT_CLIENT_ID', getenv('HUBSPOT_CLIENT_ID') ); define( 'HUBSPOT_CLIENT_SECRET', getenv('HUBSPOT_CLIENT_SECRET') ); define( 'HUBSPOT_ACCESS_TOKEN', getenv('HUBSPOT_ACCESS_TOKEN') ); define( 'HUBSPOT_REFRESH_TOKEN', getenv('HUBSPOT_REFRESH_TOKEN') ); |
.env ファイル例（サーバー上に配置し、必ず .gitignore に追加）：
|
1 2 3 4 5 |
HUBSPOT_CLIENT_ID=12345678-90ab-cdef-1234-567890abcdef HUBSPOT_CLIENT_SECRET=abcdefghijklmnopqrstuvwxyz0123456789 HUBSPOT_ACCESS_TOKEN=initial_access_token_XXXXXXXXXXXXXXXXX HUBSPOT_REFRESH_TOKEN=refresh_token_YYYYYYYYYYYYYYYYY |
6‑2．WP‑CLI 秘密管理の活用例
|
1 2 3 4 5 6 |
# 新しいシークレットを生成し、wp-config.php に直接書き込む wp secret generate --length=64 | wp config set HUBSPOT_ACCESS_TOKEN --raw # トークン更新時はオプションテーブルに保存し、コード側で get_option() で取得 wp option update hubspot_access_token 'new_long_token_string' |
メリット：CLI だけで生成・更新が完結するため、人為的ミスが減り、CI/CD パイプラインからも安全にローテーションできます。
7. 導入後の検証チェックリスト
| 項目 | 確認手順 |
|---|---|
| トラッキングコード | ブラウザでページソース → <script id="hs-script-loader"> が存在か確認 |
| リアルタイム訪問者数 | HubSpot ダッシュボード > 「レポート」>「トラッキングコード」→リアルタイムカウントが増加 |
| API 応答ログ | wp-content/debug.log に error_log() で出力されたステータスコードとレスポンス内容を確認 |
| コンタクト同期 | HubSpot の「Contacts」一覧に WordPress から送信したメールアドレスが表示されるか |
| トークン自動更新 | WP‑Cron が正しく走っているか wp cron event list を実行し、hubspot_hourly_token_refresh が存在することを確認 |
| CORS/レートリミット | 大量リクエスト時に 429 エラーが出ないか、バックオフロジックのログで検証 |
ポイント：すべての項目が OK なら本番環境でも安定稼働が期待できます。
8. トラブルシューティング
| 原因 | 対策 |
|---|---|
| アクセストークン期限切れ | hubspot_refresh_access_token() を即時実行し、取得した新トークンで再リクエスト |
| スコープ不足 | プライベートアプリ設定画面で必要なスコープを追加 → 再度認可コード取得 → 新しいアクセストークン発行 |
| 誤った Authorization ヘッダー形式 | Authorization: Bearer <TOKEN> が正しく送信されているか確認（余計な空白や改行がない） |
8‑2．CORS エラー
WordPress 側で外部から直接 HubSpot API を呼び出す場合は サーバー側プロキシ を作成し、ブラウザからは自サイトのエンドポイントだけにアクセスさせます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
add_action( 'rest_api_init', function () { register_rest_route( 'myhub/v1', '/proxy/', [ 'methods' => WP_REST_Server::CREATABLE, 'callback' => 'myhub_proxy_to_hubspot', 'permission_callback' => '__return_true', ] ); }); function myhub_proxy_to_hubspot( $request ) { header( "Access-Control-Allow-Origin: https://your-site.com" ); // 必要に応じて設定 $url = $request->get_param('url'); $args = [ 'headers' => [ 'Authorization' => 'Bearer ' . get_option('hubspot_access_token') ], 'body' => $request->get_body(), 'method' => $request->get_method(), ]; return wp_remote_request( $url, $args ); } |
8‑3．レートリミット（429）対策
HubSpot は 10 000 リクエスト/日 の上限があります。以下の実装で自動的にバックオフします。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
function hubspot_api_request( $url, $args = [], $attempt = 0 ) { $response = wp_remote_get( $url, $args ); if ( is_wp_error( $response ) ) { return $response; } $code = wp_remote_retrieve_response_code( $response ); if ( $code === 429 && $attempt < 4 ) { // Retry-After が設定されていればその秒数、なければ指数バックオフ $retry_after = intval( wp_remote_retrieve_header( $response, 'retry-after' ) ); $wait = $retry_after ? $retry_after : pow( 2, $attempt ); sleep( $wait ); return hubspot_api_request( $url, $args, $attempt + 1 ); } return $response; } |
まとめ（Key Takeaways）
- プライベートアプリ＋OAuth が唯一の認証手段。スコープは必ず URL エンコードし、リダイレクト URI を事前に登録すること。
- アクセストークンは 6 時間 で失効。
refresh_tokenと WP‑Cron による自動更新を実装すれば、手作業は不要です。 - HubSpot All‑In‑One Marketing プラグインはトラッキングコードの設置から OAuth トークン管理まで一括で提供。ノーコードでの導入が最速です。
- カスタム PHP では v3 API と正しいエンドポイントを使用し、
wp_remote_*系関数とget_option()によるトークン取得で安全かつ保守性の高い実装が可能。 - Zapier / Make.com を活用すれば 双方向自動化 がコード不要で構築でき、リード情報のリアルタイム同期が実現します。
- シークレットは
.env+wp-config.php、または WP‑CLI 秘密管理 で環境変数として保持し、Git に流出させないよう徹底してください。 - 本番導入前に テストチェックリスト（トラッキングコード・API ログ・トークン更新・CORS）をすべてクリアし、エラーは 401/429 の対処法で速やかに復旧できる体制を整えておくことが重要です。
これらの手順とベストプラクティスに沿って実装すれば、HubSpot と WordPress の連携は 安全・高速・拡張性 を兼ね備えた状態で本番運用できます。ぜひ本稿を参考に、マーケティングオートメーションの第一歩を踏み出してください。
スポンサードリンク