How to securely integrate HubSpot Contacts endpoints into WordPress custom plugins using REST API Controllers
Establishing Secure HubSpot API Authentication in WordPress
Integrating HubSpot Contacts endpoints into a custom WordPress plugin necessitates a robust and secure authentication mechanism. The HubSpot API primarily relies on OAuth 2.0 for secure access. For a custom plugin, this typically involves generating a private app or a custom app within your HubSpot account to obtain API keys and secrets. This section details the foundational steps for setting up this authentication, focusing on storing credentials securely within the WordPress environment.
The recommended approach for storing sensitive API credentials in WordPress is to leverage the WordPress options API, but with a critical caveat: these options should never be directly exposed in the frontend and should be protected from unauthorized access. For enhanced security, consider using environment variables or a dedicated secrets management system if your hosting environment supports it. However, for a self-contained plugin, secure storage within wp-config.php or a custom, non-publicly accessible configuration file is a viable, albeit less dynamic, alternative.
Storing HubSpot API Credentials
For this example, we’ll assume you’ve created a HubSpot Private App or Custom App and have obtained your Client ID and Client Secret. We will store these in WordPress constants defined in wp-config.php for immediate access and to prevent them from being directly queryable via the database.
// Add these lines to your wp-config.php file define( 'HUBSPOT_CLIENT_ID', 'YOUR_HUBSPOT_CLIENT_ID' ); define( 'HUBSPOT_CLIENT_SECRET', 'YOUR_HUBSPOT_CLIENT_SECRET' ); define( 'HUBSPOT_REDIRECT_URI', home_url( '/hubspot-callback/' ) ); // Ensure this URL is registered in HubSpot define( 'HUBSPOT_ACCESS_TOKEN_OPTION', 'hubspot_access_token' ); define( 'HUBSPOT_REFRESH_TOKEN_OPTION', 'hubspot_refresh_token' ); define( 'HUBSPOT_TOKEN_EXPIRY_OPTION', 'hubspot_token_expiry' );
The HUBSPOT_REDIRECT_URI must precisely match a URI registered within your HubSpot app settings. This is where HubSpot will redirect the user after they authorize your application. The other constants define option names for storing the OAuth tokens and their expiry times.
Implementing the HubSpot API Client Class
A well-structured PHP class is essential for encapsulating HubSpot API interactions. This class will handle authentication, token management, and making requests to the HubSpot API. We’ll focus on the OAuth 2.0 flow, including obtaining an initial access token and refreshing it when it expires.
OAuth 2.0 Token Management
The core of our client will be managing the OAuth access and refresh tokens. This involves:
- Redirecting the user to HubSpot for authorization.
- Handling the callback from HubSpot, exchanging the authorization code for tokens.
- Storing and retrieving tokens from the WordPress options database.
- Checking token expiry and initiating a refresh if necessary.
<?php
/**
* HubSpot API Client for WordPress.
* Handles OAuth 2.0 authentication and API requests.
*/
class HubSpot_API_Client {
private $client_id;
private $client_secret;
private $redirect_uri;
private $access_token_option;
private $refresh_token_option;
private $token_expiry_option;
public function __construct() {
$this->client_id = defined( 'HUBSPOT_CLIENT_ID' ) ? HUBSPOT_CLIENT_ID : '';
$this->client_secret = defined( 'HUBSPOT_CLIENT_SECRET' ) ? HUBSPOT_CLIENT_SECRET : '';
$this->redirect_uri = defined( 'HUBSPOT_REDIRECT_URI' ) ? HUBSPOT_REDIRECT_URI : '';
$this->access_token_option = defined( 'HUBSPOT_ACCESS_TOKEN_OPTION' ) ? HUBSPOT_ACCESS_TOKEN_OPTION : 'hubspot_access_token';
$this->refresh_token_option = defined( 'HUBSPOT_REFRESH_TOKEN_OPTION' ) ? HUBSPOT_REFRESH_TOKEN_OPTION : 'hubspot_refresh_token';
$this->token_expiry_option = defined( 'HUBSPOT_TOKEN_EXPIRY_OPTION' ) ? HUBSPOT_TOKEN_EXPIRY_OPTION : 'hubspot_token_expiry';
if ( empty( $this->client_id ) || empty( $this->client_secret ) ) {
// Log an error or throw an exception if credentials are not set.
error_log( 'HubSpot API Client: Client ID or Secret not configured.' );
}
}
/**
* Get the authorization URL for HubSpot.
*
* @return string The authorization URL.
*/
public function get_authorization_url() {
$scopes = 'contacts.basic.read contacts.basic.write'; // Define necessary scopes
$params = array(
'client_id' => $this->client_id,
'redirect_uri' => $this->redirect_uri,
'scope' => $scopes,
'response_type' => 'code',
);
return 'https://app.hubspot.com/oauth/authorize?' . http_build_query( $params );
}
/**
* Exchange authorization code for access and refresh tokens.
*
* @param string $code The authorization code received from HubSpot.
* @return bool True on success, false on failure.
*/
public function exchange_code_for_token( $code ) {
if ( empty( $code ) ) {
return false;
}
$url = 'https://api.hubapi.com/oauth/v1/token';
$body = array(
'grant_type' => 'authorization_code',
'client_id' => $this->client_id,
'client_secret' => $this->client_secret,
'redirect_uri' => $this->redirect_uri,
'code' => $code,
);
$response = wp_remote_post( $url, array(
'method' => 'POST',
'timeout' => 45,
'body' => $body,
) );
if ( is_wp_error( $response ) ) {
error_log( 'HubSpot API Client: Error exchanging code for token: ' . $response->get_error_message() );
return false;
}
$body_json = wp_remote_retrieve_body( $response );
$data = json_decode( $body_json, true );
if ( isset( $data['access_token'] ) && isset( $data['refresh_token'] ) && isset( $data['expires_in'] ) ) {
$expiry_time = time() + intval( $data['expires_in'] );
update_option( $this->access_token_option, $data['access_token'] );
update_option( $this->refresh_token_option, $data['refresh_token'] );
update_option( $this->token_expiry_option, $expiry_time );
return true;
} else {
error_log( 'HubSpot API Client: Failed to retrieve valid tokens. Response: ' . print_r( $data, true ) );
return false;
}
}
/**
* Refresh the access token using the refresh token.
*
* @return bool True on success, false on failure.
*/
public function refresh_access_token() {
$refresh_token = get_option( $this->refresh_token_option );
if ( empty( $refresh_token ) ) {
error_log( 'HubSpot API Client: No refresh token available to refresh access token.' );
return false;
}
$url = 'https://api.hubapi.com/oauth/v1/token';
$body = array(
'grant_type' => 'refresh_token',
'client_id' => $this->client_id,
'client_secret' => $this->client_secret,
'redirect_uri' => $this->redirect_uri, // Required even for refresh
'refresh_token' => $refresh_token,
);
$response = wp_remote_post( $url, array(
'method' => 'POST',
'timeout' => 45,
'body' => $body,
) );
if ( is_wp_error( $response ) ) {
error_log( 'HubSpot API Client: Error refreshing access token: ' . $response->get_error_message() );
return false;
}
$body_json = wp_remote_retrieve_body( $response );
$data = json_decode( $body_json, true );
if ( isset( $data['access_token'] ) && isset( $data['expires_in'] ) ) {
$expiry_time = time() + intval( $data['expires_in'] );
update_option( $this->access_token_option, $data['access_token'] );
// The refresh token might be rotated, so update it if provided.
if ( isset( $data['refresh_token'] ) ) {
update_option( $this->refresh_token_option, $data['refresh_token'] );
}
update_option( $this->token_expiry_option, $expiry_time );
return true;
} else {
error_log( 'HubSpot API Client: Failed to refresh tokens. Response: ' . print_r( $data, true ) );
// If refresh fails, it might be due to an invalid refresh token. Clear stored tokens.
delete_option( $this->access_token_option );
delete_option( $this->refresh_token_option );
delete_option( $this->token_expiry_option );
return false;
}
}
/**
* Get the current access token, refreshing if necessary.
*
* @return string|false The access token or false if not authenticated.
*/
public function get_access_token() {
$access_token = get_option( $this->access_token_option );
$expiry_time = get_option( $this->token_expiry_option );
// Check if token exists and is not expired
if ( ! empty( $access_token ) && $expiry_time && time() < $expiry_time ) {
return $access_token;
}
// Token is expired or missing, attempt to refresh
if ( $this->refresh_access_token() ) {
return get_option( $this->access_token_option );
}
// If refresh failed, return false to indicate no valid token
return false;
}
/**
* Check if the user is currently authenticated with HubSpot.
*
* @return bool True if authenticated, false otherwise.
*/
public function is_authenticated() {
return ! empty( $this->get_access_token() );
}
/**
* Make a request to the HubSpot API.
*
* @param string $method The HTTP method (GET, POST, PUT, DELETE).
* @param string $endpoint The API endpoint (e.g., '/contacts/v1/contact').
* @param array $args Arguments for the request (e.g., 'body', 'query').
* @return array|WP_Error The API response or a WP_Error object.
*/
public function make_request( $method, $endpoint, $args = array() ) {
$access_token = $this->get_access_token();
if ( ! $access_token ) {
return new WP_Error( 'hubspot_auth_error', __( 'HubSpot authentication failed. Please re-authenticate.', 'your-text-domain' ) );
}
$base_url = 'https://api.hubapi.com';
$url = $base_url . $endpoint;
$default_args = array(
'headers' => array(
'Authorization' => 'Bearer ' . $access_token,
'Content-Type' => 'application/json',
),
'timeout' => 30,
);
// Merge user-provided args with defaults
$request_args = wp_parse_args( $args, $default_args );
// Ensure body is JSON encoded if it's an array
if ( isset( $request_args['body'] ) && is_array( $request_args['body'] ) ) {
$request_args['body'] = json_encode( $request_args['body'] );
}
$response = wp_remote_request( $url, array_merge( $default_args, $request_args, array( 'method' => strtoupper( $method ) ) ) );
if ( is_wp_error( $response ) ) {
return $response;
}
$response_code = wp_remote_retrieve_response_code( $response );
$response_body = wp_remote_retrieve_body( $response );
$data = json_decode( $response_body, true );
// Handle HubSpot API errors (e.g., 401 Unauthorized, 400 Bad Request)
if ( $response_code >= 400 ) {
$error_message = isset( $data['message'] ) ? $data['message'] : 'Unknown HubSpot API error.';
// If it's a 401, it might mean the token expired and refresh failed.
if ( $response_code === 401 ) {
// Attempt to refresh token again, though get_access_token should have done this.
// This is a fallback.
if ( $this->refresh_access_token() ) {
// Retry the request with the new token
return $this->make_request( $method, $endpoint, $args );
} else {
// If refresh still fails, clear tokens and return error.
delete_option( $this->access_token_option );
delete_option( $this->refresh_token_option );
delete_option( $this->token_expiry_option );
return new WP_Error( 'hubspot_auth_error', __( 'HubSpot authentication failed and could not be refreshed. Please re-authenticate.', 'your-text-domain' ) );
}
}
return new WP_Error( 'hubspot_api_error', sprintf( __( 'HubSpot API Error (%d): %s', 'your-text-domain' ), $response_code, $error_message ), $data );
}
return $data;
}
// --- Specific Contact Endpoints ---
/**
* Get a list of contacts.
*
* @param array $params Query parameters (e.g., 'count', 'property').
* @return array|WP_Error
*/
public function get_contacts( $params = array() ) {
$endpoint = '/contacts/v1/lists/all/contacts/all'; // This is a legacy endpoint, consider v3
// For v3: '/crm/v3/objects/contacts'
// For v1, properties are often passed as query params, e.g., 'property=email&property=firstname'
// For v3, properties are in the request body or query params depending on the call.
// Let's stick to v1 for simplicity in this example, but note v3 is preferred for new development.
// Example for v1:
$query_params = array();
if ( ! empty( $params['count'] ) ) {
$query_params['count'] = intval( $params['count'] );
}
if ( ! empty( $params['property'] ) ) {
if ( is_array( $params['property'] ) ) {
$query_params['property'] = implode( ',', $params['property'] );
} else {
$query_params['property'] = $params['property'];
}
}
if ( ! empty( $params['vidOffset'] ) ) {
$query_params['vidOffset'] = $params['vidOffset'];
}
$args = array();
if ( ! empty( $query_params ) ) {
$args['query'] = $query_params;
}
return $this->make_request( 'GET', $endpoint, $args );
}
/**
* Get a single contact by vid.
*
* @param int $vid The contact's vid.
* @param array $params Query parameters (e.g., 'property').
* @return array|WP_Error
*/
public function get_contact_by_vid( $vid, $params = array() ) {
$endpoint = '/contacts/v1/contact/vid/' . intval( $vid );
$args = array();
if ( ! empty( $params['property'] ) ) {
$args['query'] = array( 'property' => $params['property'] );
}
return $this->make_request( 'GET', $endpoint, $args );
}
/**
* Create a new contact.
*
* @param array $properties An array of contact properties (e.g., ['email' => '[email protected]', 'firstname' => 'Test']).
* @return array|WP_Error
*/
public function create_contact( $properties ) {
$endpoint = '/contacts/v1/contact';
$args = array(
'body' => array(
'properties' => $properties,
),
);
return $this->make_request( 'POST', $endpoint, $args );
}
/**
* Update an existing contact.
*
* @param int $vid The contact's vid.
* @param array $properties An array of contact properties to update.
* @return array|WP_Error
*/
public function update_contact( $vid, $properties ) {
$endpoint = '/contacts/v1/contact/vid/' . intval( $vid );
$args = array(
'body' => array(
'properties' => $properties,
),
);
return $this->make_request( 'POST', $endpoint, $args ); // Note: HubSpot uses POST for updates in v1
}
/**
* Update or create a contact based on email.
* This is a common pattern. HubSpot's v1 API doesn't have a direct upsert by email,
* but you can achieve it by first trying to get the contact by email, then updating or creating.
* For v3, there's a dedicated upsert endpoint.
*
* @param array $properties An array of contact properties, must include 'email'.
* @return array|WP_Error
*/
public function upsert_contact_by_email( $properties ) {
if ( ! isset( $properties['email'] ) ) {
return new WP_Error( 'invalid_property', __( 'Email property is required for upsert.', 'your-text-domain' ) );
}
// Try to find contact by email first (using v1 endpoint for consistency in this example)
$contact_data = $this->get_contact_by_email( $properties['email'], array( 'property' => array_keys( $properties ) ) );
if ( is_wp_error( $contact_data ) ) {
// If there's an error other than "not found", return it.
// HubSpot API might return 404 or a specific message for not found.
// A more robust check would inspect the error code/message.
// For simplicity, we'll assume any error here means we should try to create.
// In a real-world scenario, you'd want to differentiate "not found" from other errors.
error_log( 'HubSpot API Client: Error fetching contact by email, attempting to create. Error: ' . $contact_data->get_error_message() );
return $this->create_contact( $properties );
}
// If contact exists, update it
if ( isset( $contact_data['vid'] ) ) {
return $this->update_contact( $contact_data['vid'], $properties );
}
// Fallback if contact_data is not as expected
return $this->create_contact( $properties );
}
/**
* Get a contact by email address.
* Note: This is a convenience method, the underlying API might not directly support
* searching by email in all versions without specific property requests.
* For v1, you typically query for properties and filter results.
* For v3, there's a search endpoint.
*
* @param string $email The contact's email address.
* @param array $params Query parameters (e.g., 'property').
* @return array|WP_Error
*/
public function get_contact_by_email( $email, $params = array() ) {
// HubSpot API v1 doesn't have a direct GET /contacts/v1/contact/email/{email} endpoint.
// You need to query all contacts and filter, or use the search API if available.
// A common workaround is to use the /contacts/v1/contact/email/{email} endpoint,
// but this is often undocumented or subject to change.
// The most reliable way for v1 is to fetch contacts with specific properties and filter.
// However, for simplicity and common usage, let's assume a direct lookup is possible
// or that the `make_request` can handle it if the endpoint exists.
// A more robust v1 implementation would involve fetching a list and iterating.
// Let's use the documented way to get a contact by email if properties are specified.
// This endpoint is often used for lookup.
$endpoint = '/contacts/v1/contact/email/' . urlencode( $email );
$args = array();
if ( ! empty( $params['property'] ) ) {
if ( is_array( $params['property'] ) ) {
$args['query'] = array( 'property' => implode( ',', $params['property'] ) );
} else {
$args['query'] = array( 'property' => $params['property'] );
}
} else {
// If no properties are specified, request common ones to ensure we get a result if it exists.
$args['query'] = array( 'property' => 'email,firstname,lastname' );
}
$response = $this->make_request( 'GET', $endpoint, $args );
// The v1 API returns a 404 if the contact doesn't exist.
// We need to check for this specific case.
if ( is_wp_error( $response ) ) {
// Check if the error is a "not found" scenario.
// This check might need refinement based on actual HubSpot error responses.
if ( $response->get_error_code() === 'hubspot_api_error' && isset( $response->get_error_data()['status'] ) && $response->get_error_data()['status'] === 404 ) {
return new WP_Error( 'contact_not_found', __( 'Contact not found.', 'your-text-domain' ), 404 );
}
return $response; // Return other errors as is.
}
return $response;
}
// Add more methods for other HubSpot endpoints as needed.
}
?>
Handling the OAuth Callback
A dedicated WordPress endpoint (e.g., a page or a custom rewrite rule) is required to handle the redirect from HubSpot after the user authorizes your application. This endpoint will receive the authorization code as a query parameter.
<?php
/**
* Handle HubSpot OAuth callback.
* This should be hooked into WordPress initialization.
*/
function handle_hubspot_oauth_callback() {
// Check if we are on the specific callback page and if a 'code' parameter exists.
// Ensure HUBSPOT_REDIRECT_URI is set to home_url( '/hubspot-callback/' )
if ( isset( $_GET['code'] ) && isset( $_GET['state'] ) && $_SERVER['REQUEST_URI'] === parse_url( HUBSPOT_REDIRECT_URI, PHP_URL_PATH ) ) {
$hubspot_client = new HubSpot_API_Client();
// Verify the state parameter to prevent CSRF attacks.
// In a real-world scenario, you'd generate and store a state token in the user's session
// before redirecting to HubSpot, and then verify it here.
// For simplicity, we'll skip state verification in this basic example.
// if ( ! wp_verify_nonce( $_GET['state'], 'hubspot_oauth_nonce' ) ) {
// wp_die( __( 'Invalid state parameter. Please try again.', 'your-text-domain' ) );
// }
$code = sanitize_text_field( $_GET['code'] );
if ( $hubspot_client->exchange_code_for_token( $code ) ) {
// Token exchange successful. Redirect to a success page or admin area.
// Clear the 'code' and 'state' from the URL.
wp_redirect( remove_query_arg( array( 'code', 'state' ), HUBSPOT_REDIRECT_URI ) );
exit;
} else {
// Token exchange failed. Display an error message.
wp_die( __( 'HubSpot authentication failed during token exchange. Please try again.', 'your-text-domain' ) );
}
}
}
add_action( 'init', 'handle_hubspot_oauth_callback' );
/**
* Add a button or link to initiate the OAuth flow.
* This could be in an admin page or a shortcode.
*/
function hubspot_auth_button() {
$hubspot_client = new HubSpot_API_Client();
if ( ! $hubspot_client->is_authenticated() ) {
$auth_url = $hubspot_client->get_authorization_url();
// In a real app, you'd generate a nonce for the state parameter:
// $state = wp_create_nonce( 'hubspot_oauth_nonce' );
// $auth_url .= '&state=' . urlencode( $state );
echo '<p><a href="' . esc_url( $auth_url ) . '" class="button button-primary">' . __( 'Connect to HubSpot', 'your-text-domain' ) . '</a></p>';
} else {
echo '<p>' . __( 'Successfully connected to HubSpot.', 'your-text-domain' ) . '</p>';
// Optionally add a disconnect button here.
}
}
// Example usage: Add this function to a shortcode or an admin page.
// add_shortcode( 'hubspot_connect_button', 'hubspot_auth_button' );
?>
To make the callback URL work, you need to ensure that the path specified in HUBSPOT_REDIRECT_URI (e.g., /hubspot-callback/) is handled. The simplest way is to create a page in WordPress with the slug hubspot-callback. The init hook ensures this callback is processed early in the WordPress loading sequence.
Integrating HubSpot Contacts Data into WordPress
Once authentication is handled, you can use the HubSpot_API_Client class to fetch and manipulate contact data. This section demonstrates how to retrieve contacts and create/update them.
Fetching Contacts
Retrieving contacts involves calling the get_contacts or get_contact_by_vid methods. You can specify which properties you need to optimize the API calls.
<?php
// Assuming $hubspot_client is an instance of HubSpot_API_Client
$hubspot_client = new HubSpot_API_Client();
if ( $hubspot_client->is_authenticated() ) {
// Get the first 10 contacts, requesting email and firstname properties
$contacts_data = $hubspot_client->get_contacts( array(
'count' => 10,
'property' => array( 'email', 'firstname', 'lastname' ),
) );
if ( ! is_wp_error( $contacts_data ) && isset( $contacts_data['contacts'] ) ) {
echo '<h2>HubSpot Contacts:</h2>';
echo '<ul>';
foreach ( $contacts_data['contacts'] as $contact ) {
$vid = $contact['vid'];
$properties = $contact['properties'];
$email = isset( $properties['email']['value'] ) ? $properties['email']['value'] : 'N/A';
$firstname = isset( $properties['firstname']['value'] ) ? $properties['firstname']['value'] : '';
$lastname = isset( $properties['lastname']['value'] ) ? $properties['lastname']['value'] : '';
echo '<li>' . esc_html( $firstname ) . ' ' . esc_html( $lastname ) . ' (' . esc_html( $email ) . ') [VID: ' . intval( $vid ) . ']</li>';
}
echo '</ul>';
} elseif ( is_wp_error( $contacts_data ) ) {
echo '<p style="color:red;">Error fetching contacts: ' . esc_html( $contacts_data->get_error_message() ) . '</p>';
} else {
echo '<p>No contacts found or unexpected response format.</p>';
}
} else {
echo '<p>' . __( 'Not connected to HubSpot. Please connect first.', 'your-text-domain' ) . '</p>';
// Display the connect button
hubspot_auth_button();
}
?>
Creating and Updating Contacts
The create_contact, update_contact, and upsert_contact_by_email methods facilitate data synchronization. The upsert_contact_by_email is particularly useful for ensuring contact uniqueness based on email address.
<?php
// Assuming $hubspot_client is an instance of HubSpot_API_Client
$hubspot_client = new HubSpot_API_Client();
if ( $hubspot_client->is_authenticated() ) {
// --- Example: Create a new contact ---
$new_contact_properties = array(
'email' => '[email protected]',
'firstname' => 'New',
'lastname' => 'User',
'company' => 'Example Corp',
);
$created_contact = $hubspot_client->create_contact( $new_contact_properties );
if ( ! is_wp_error( $created_contact ) ) {
echo '<p>Contact created successfully! VID: ' . esc_html( $created_contact['vid'] ) . '</p>';
} else {
echo '<p style="color:red;">Error creating contact: ' . esc_html( $created_contact->get_error_message() ) . '</p>';