Configuration

The published config file (config/hubspot.php) allows you to configure the API connection, rate limiting, query caching, default properties and associations per object type, HTTP timeouts, request logging, and webhook handling.

Full Config Reference

php

return [
    'base_url' => env('HUBSPOT_BASE_URL', 'https://api.hubapi.com'),
    'access_token' => env('HUBSPOT_ACCESS_TOKEN'),

    // Property definition caching (set to false to disable)
    'definitions' => [
        'cache' => '30 days',
    ],

    // Rate limiting per HubSpot tier
    // Free/Starter: 100 requests per 10 seconds
    // Professional/Enterprise: 150 requests per 10 seconds
    'rate_limit' => [
        'requests' => (int) env('HUBSPOT_RATE_LIMIT_REQUESTS', 100),
        'per_seconds' => (int) env('HUBSPOT_RATE_LIMIT_PER_SECONDS', 10),
    ],

    // Query-level caching (requires ->cache() call on queries)
    'cache' => [
        'enabled' => (bool) env('HUBSPOT_CACHE_ENABLED', false),
        'store' => env('HUBSPOT_CACHE_STORE'),
        'prefix' => env('HUBSPOT_CACHE_PREFIX', 'hubspot'),
        'ttl' => (int) env('HUBSPOT_CACHE_TTL', 3600),
        'auto_invalidate' => (bool) env('HUBSPOT_CACHE_AUTO_INVALIDATE', true),
    ],

    // Default properties and associations loaded for each object type
    'contacts' => [
        'include_properties' => ['firstname', 'lastname', 'email'],
        'include_associations' => ['companies', 'contact', 'deals', 'tickets'],
    ],

    'companies' => [
        'include_properties' => ['domain', 'name', 'phone'],
        'include_associations' => ['contacts', 'deals', 'tickets'],
    ],

    // ... additional object types ...

    // Pipeline caching (set to false to disable)
    'pipelines' => [
        'cache' => '1 hour',
    ],

    'http' => [
        'timeout' => (int) env('HUBSPOT_HTTP_TIMEOUT', 10),
        'connect_timeout' => (int) env('HUBSPOT_HTTP_CONNECT_TIMEOUT', 10),
    ],

    // API request/response logging
    'logging' => [
        'enabled' => (bool) env('HUBSPOT_LOGGING_ENABLED', false),
        'channel' => env('HUBSPOT_LOGGING_CHANNEL'),
        'log_bodies' => (bool) env('HUBSPOT_LOGGING_BODIES', false),
        'body_sanitizer' => null,
    ],

    // Webhook handling (opt-in, activated by setting client_secret)
    'webhooks' => [
        'client_secret' => env('HUBSPOT_WEBHOOK_SECRET'),
        'path' => env('HUBSPOT_WEBHOOK_PATH', 'hubspot/webhooks'),
        'middleware' => ['api'],
        'verify_signature' => true,
        'tolerance' => 300,
        'queue' => ['enabled' => false, 'connection' => null, 'queue' => null],
        'hydrate_models' => true,
        'only' => [],
        'except' => [],
        'deduplicate' => false,
        'deduplicate_ttl' => 3600,
    ],
];

Config Options

API Connection

Option	Description	Default
`base_url`	The HubSpot API base URL. You should not need to change this.	`https://api.hubapi.com`
`access_token`	Your HubSpot private app access token.	`null`

Property Definitions

Option	Description	Default
`definitions.cache`	How long to cache property definitions fetched from HubSpot. Set to `false` to disable caching.	`'30 days'`

Rate Limiting

Rate limits are enforced automatically via Saloon and backed by Laravel Cache.

Option	Description	Default
`rate_limit.requests`	Maximum number of requests allowed per window. Free/Starter plans allow 100; Professional/Enterprise plans allow 150.	`100`
`rate_limit.per_seconds`	The time window in seconds for the rate limit.	`10`

Query Caching

Query caching is opt-in. You must call ->cache() on a query for results to be cached. These options configure the defaults.

Option	Description	Default
`cache.enabled`	Whether query caching is available.	`false`
`cache.store`	The Laravel cache store to use. `null` uses the default store.	`null`
`cache.prefix`	Key prefix for all cached queries.	`'hubspot'`
`cache.ttl`	Default time-to-live in seconds for cached queries.	`3600`
`cache.auto_invalidate`	Automatically invalidate cached queries when write operations occur.	`true`

Object Type Defaults

Each object type key (e.g. contacts, deals, companies) accepts:

Option	Description
`include_properties`	Properties included by default on every query for that type.
`include_associations`	Associations included by default on every query for that type.

Pipelines

Option	Description	Default
`pipelines.cache`	How long to cache pipeline definitions. Set to `false` to disable.	`'1 hour'`

HTTP

Option	Description	Default
`http.timeout`	Request timeout in seconds.	`10`
`http.connect_timeout`	Connection timeout in seconds.	`10`

Logging

Option	Description	Default
`logging.enabled`	Enable API request/response logging.	`false`
`logging.channel`	The Laravel log channel to use. `null` uses the default channel.	`null`
`logging.log_bodies`	Whether to log request and response bodies.	`false`
`logging.body_sanitizer`	A callable for sanitizing logged bodies (e.g. to redact PII).	`null`

Webhooks

Webhook handling is opt-in and activated by setting the client_secret.

Option	Description	Default
`webhooks.client_secret`	Your HubSpot app client secret, used for HMAC-SHA256 signature verification.	`null`
`webhooks.path`	The URI path where the webhook endpoint is registered.	`'hubspot/webhooks'`
`webhooks.middleware`	Middleware applied to the webhook route.	`['api']`
`webhooks.verify_signature`	Whether to verify the HMAC-SHA256 signature on incoming requests.	`true`
`webhooks.tolerance`	Maximum age of a webhook request in seconds before it is rejected.	`300`
`webhooks.queue.enabled`	Whether to dispatch webhook events to a queue.	`false`
`webhooks.queue.connection`	The queue connection to use. `null` uses the default.	`null`
`webhooks.queue.queue`	The queue name to use. `null` uses the default.	`null`
`webhooks.hydrate_models`	Whether to automatically hydrate CRM models from webhook payloads.	`true`
`webhooks.only`	An array of event types to process. Empty means all.	`[]`
`webhooks.except`	An array of event types to ignore.	`[]`
`webhooks.deduplicate`	Whether to deduplicate webhook events.	`false`
`webhooks.deduplicate_ttl`	TTL in seconds for the deduplication cache.	`3600`

Environment Variables

All available environment variables at a glance:

Variable	Description	Default
`HUBSPOT_BASE_URL`	API base URL	`https://api.hubapi.com`
`HUBSPOT_ACCESS_TOKEN`	Private app access token
`HUBSPOT_RATE_LIMIT_REQUESTS`	Rate limit request count	`100`
`HUBSPOT_RATE_LIMIT_PER_SECONDS`	Rate limit window in seconds	`10`
`HUBSPOT_CACHE_ENABLED`	Enable query caching	`false`
`HUBSPOT_CACHE_STORE`	Cache store name	Default store
`HUBSPOT_CACHE_PREFIX`	Cache key prefix	`hubspot`
`HUBSPOT_CACHE_TTL`	Cache TTL in seconds	`3600`
`HUBSPOT_CACHE_AUTO_INVALIDATE`	Auto-invalidate cache on writes	`true`
`HUBSPOT_HTTP_TIMEOUT`	HTTP request timeout in seconds	`10`
`HUBSPOT_HTTP_CONNECT_TIMEOUT`	HTTP connection timeout in seconds	`10`
`HUBSPOT_LOGGING_ENABLED`	Enable request logging	`false`
`HUBSPOT_LOGGING_CHANNEL`	Log channel name	Default channel
`HUBSPOT_LOGGING_BODIES`	Log request/response bodies	`false`
`HUBSPOT_WEBHOOK_SECRET`	Webhook client secret
`HUBSPOT_WEBHOOK_PATH`	Webhook endpoint path	`hubspot/webhooks`

Configuration ​

Full Config Reference ​

Config Options ​

API Connection ​

Property Definitions ​

Rate Limiting ​

Query Caching ​

Object Type Defaults ​

Pipelines ​

HTTP ​

Logging ​

Webhooks ​

Environment Variables ​