Hubspot Laravel Package

Getting Started

Install Laravel Socialite plus the provider package you need. Each provider in the SocialiteProviders/Providers monorepo is published as its own Composer package:

composer require laravel/socialite socialiteproviders/hubspot

Look first at the provider-specific page (e.g. https://socialiteproviders.com/Hubspot/) for its required config and scopes, then at the monorepo README for the shared event-listener pattern.

Register the provider via the SocialiteWasCalled event. In Laravel 10 and earlier this typically lives in app/Providers/EventServiceProvider.php; in Laravel 11+ put it in AppServiceProvider::boot() or a dedicated provider listed in bootstrap/providers.php:

use SocialiteProviders\Manager\SocialiteWasCalled;

Event::listen(function (SocialiteWasCalled $event) {
    $event->extendSocialite('hubspot', \SocialiteProviders\Hubspot\Provider::class);
});

Add credentials to config/services.php:

'hubspot' => [
    'client_id' => env('HUBSPOT_CLIENT_ID'),
    'client_secret' => env('HUBSPOT_CLIENT_SECRET'),
    'redirect' => env('HUBSPOT_REDIRECT_URI'),
],

Then use the driver like any core Socialite provider:

return Socialite::driver('hubspot')->redirect();

// callback
$user = Socialite::driver('hubspot')->user();

First use case: adding an OAuth provider that Laravel Socialite doesn't ship with (HubSpot, Stripe Connect, etc.) without hand-writing an OAuth client. Patch 4.1.3 migrates the HubSpot provider to HubSpot's 2026-03 OAuth endpoints, so run composer update socialiteproviders/hubspot if HubSpot is in your stack.

Implementation Patterns

• Keep one listener per provider, ideally grouped in a dedicated service provider as your provider count grows.
• Set scopes explicitly with ->scopes([...]) or ->setScopes([...]); many providers have non-obvious defaults and vendor dashboards often require exact scope strings.
• Use stateless flows for API-only integrations: Socialite::driver('hubspot')->stateless()->user() when you don't have a session/state store.
• Capture refresh tokens from $user->accessTokenResponseBody['refresh_token'] in the callback and refresh against the provider's token endpoint; verify per-provider support before relying on it.
• Pass extra OAuth parameters with ->with(['prompt' => 'consent']) (e.g. access_type=offline for Google-style providers).
• For multi-tenant apps, set the redirect URI per request (Socialite::driver('hubspot')->redirectUrl($url) where supported) or override services.<provider>.redirect at runtime.
• Extend a provider when the package lags a vendor change: subclass it and override getAuthUrl, getTokenUrl, or mapUserToObject rather than forking the whole package.
• In tests, use Socialite::shouldReceive('driver->user') or HTTP fakes for the token/user endpoints; don't hit real OAuth in CI.
• Wrap callbacks in try/catch for Laravel\Socialite\Two\InvalidStateException and GuzzleHttp\Exception\ClientException; surface a friendly error and restart the flow.

Gotchas and Tips

• Provider packages version independently, while monorepo tags like 4.1.3 describe the aggregate release. Confirm the fix landed with composer show socialiteproviders/hubspot. The 4.1.3 change moves HubSpot OAuth to the 2026-03 endpoints; pinned older versions may still call deprecated endpoints and fail token exchange.
• OAuth endpoints are hardcoded in providers and change when vendors version their APIs. After updating, re-test the full redirect → callback → token → user flow, since endpoint changes can alter token response shapes.
• Run php artisan config:clear after editing config/services.php; cached config will otherwise keep stale credentials or redirect URIs.
• Redirect URIs must match exactly (scheme, host, path, trailing slash) in both the provider dashboard and services.php.
• If the event listener appears not to fire, check that the driver name in Socialite::driver('...') matches the first argument to extendSocialite, and that the listener is registered in the current environment.
• Laravel 11+ has no default EventServiceProvider; register the listener in AppServiceProvider::boot() or add a custom provider to bootstrap/providers.php.
• Some providers require extra config keys or packages (tenant/region IDs, JWT libs); read the provider page, not just the generic README.
• Never commit provider secrets. For local development use a tunnel (ngrok, Valet share, etc.) and update the registered redirect URI.
• Pin major versions in composer.json and skim provider changelogs before upgrades; patch releases like 4.1.3 are usually safe but can still change vendor endpoint behavior.
• If a provider falls behind a vendor API change, the intended extension point is subclassing the provider and overriding endpoint methods—avoid editing files in vendor/.