This guide explains how Eventlink’s HubSpot integration works under the hood: the OAuth connection, the CRM card endpoint, the workflow custom action endpoints, request signature verification, and the public registration signal used by embedded HubSpot forms. For the organizer-facing behavior, see HubSpot.

Connection lifecycle

  1. An organizer clicks Connect in Settings > Integrations. The dashboard starts an OAuth link flow (linkSocialAccount) with provider id hubspot.
  2. After HubSpot redirects back, the dashboard claims the connection with POST /api/v1/dashboard/integrations/claim. The claim moves the OAuth tokens from the user-level linked account to a workspace-level integration record and deletes the linked account row, so the connection belongs to the workspace, not the user.
  3. On claim, Eventlink introspects the access token and stores the granted scopes, along with portal id (hubspotPortalId), region, and hub domain in integration metadata when available. It also ensures its custom contact properties exist in the portal. Every HubSpot-facing endpoint resolves the workspace by matching portalId against that metadata.
  4. Disconnecting deletes the workspace integration record and removes the Eventlink install from the HubSpot portal.

OAuth scopes

Eventlink requests these scopes (connections made before a scope was added keep working but the related feature is gated until the organizer reconnects):
  • oauth, forms
  • crm.objects.contacts.read, crm.objects.contacts.write
  • crm.schemas.contacts.read, crm.schemas.contacts.write
  • crm.lists.read, crm.lists.write
  • crm.objects.owners.read — owner display names on contacts
  • crm.objects.marketing_events.read, crm.objects.marketing_events.write — Marketing Events + attendance
  • marketing.campaigns.read, marketing.campaigns.write, marketing.campaigns.revenue.read — campaign container and revenue attribution
  • crm.objects.deals.read
Access tokens are refreshed server-side; connection state is tracked as connected or needs_reconnect.

CRM card endpoint

POST /api/v1/integrations/hubspot/cards/registrations Called by HubSpot’s hubspot.fetch when the CRM card renders on a contact record. Returns Eventlink registrations for the card’s contacts, scoped to the workspace whose integration metadata matches portalId. Query parameters: Request body: Response: { items, nextCursor }, where each item is:
Behavior notes:
  • Results are limited to registrations on published, non-canceled events. If neither emails nor hubspotContactIds are given, the response is an empty page.
  • no_show maps to no-show; confirmed, pending, and waitlisted all surface as registered; rejected stays rejected. ticketType is paid when the ticket price is greater than zero.
  • Errors: 401 invalid signature, 403 when the connection needs a reconnect, 404 when no (or more than one) workspace matches the portal.

Workflow custom action endpoints

All live under /api/v1/integrations/hubspot/actions and are signed with the HubSpot custom-action signature (see below).

POST /actions/options/events

Fetches the event dropdown options for the custom action configuration UI. Body: { portalId, query? }. Response: { options: [{ label, value, description? }] } — published Eventlink events for the portal’s workspace.

POST /actions/register

Registers the enrolled contact on an event. Body: Response: { ok: true, registrationId, status, eventUrl }. Errors include 404 (workspace or event not found) and 409 (event at capacity).

POST /actions/invite

Sends an Eventlink event invite to a contact. Body: { portalId, eventId, email, name?, hostMessage? }. Response: { ok: true, inviteUrl }.

POST /actions/status

Updates an existing registration’s status. Body: { portalId, eventId, email? | registrationId?, status }, where status is one of approved, rejected, cancelled, checked_in. Response: { ok: true, registrationId, status }. Approving a registration on a full event returns 409.

Request signature verification

Three HubSpot signature schemes are enforced, and every comparison runs in constant time. A request with a missing or invalid signature is rejected with 401. The CRM card and workflow custom action schemes are HMAC-SHA256 over the raw request with the app’s client secret, base64-encoded.
  • CRM card (official v3) — headers X-HubSpot-Signature-v3 and X-HubSpot-Request-Timestamp. Source string: METHOD + request-uri + raw body + timestamp. Timestamps more than five minutes from now are rejected. The request URI is normalized the way HubSpot signs it: the fragment is dropped, and only the reserved characters HubSpot decodes (%3A, %2F, %3F, %40, …) are decoded, and only in the query string. + in emails is deliberately left encoded.
  • Workflow custom actions — header X-HubSpot-Signature. Source string: METHOD + path + query-string + raw body.
  • Inbound webhooks (v1) — header X-HubSpot-Signature with signature version v1. The signature is the lowercase hexadecimal SHA-256 hash of the client secret concatenated with the raw request body: SHA-256(clientSecret + rawBody).
Implementation: apps/api/src/modules/integrations/verify-hubspot-signature.ts.

Inbound webhooks

POST /api/v1/integrations/hubspot/webhooks HubSpot posts batches of CRM events here. After the v1 signature check, Eventlink resolves each portal to a workspace and schedules one registrations pull per portal. When HUBSPOT_SYNC_QUEUE is bound, Eventlink enqueues each pull as an inboundPortal message; the queue consumer runs the pull with queue retries. If the queue is unbound or enqueueing fails, Eventlink runs the pull inline, using waitUntil when available. contact.privacyDeletion is acknowledged and does not enqueue a pull. The hourly backfill cron is the safety net if queued or background work is lost.

Public registration signal

POST /api/v1/public/orgs/{orgSlug}/events/{eventSlug}/hubspot-registration-signal Unauthenticated endpoint called from the HubSpot form embed’s onFormSubmitted callback on public event pages. Body: Response: { ok: true, processed, created }. Eventlink fetches recent submissions for the bound form from the HubSpot Forms API on the workspace’s connection and upserts registrations for the signaled event. Returns 409 when the event is not configured for HubSpot registration and 503 when HubSpot is unavailable. The public event API also exposes POST /api/v1/public/orgs/{orgSlug}/events/{eventSlug}/registrations for Eventlink-native registration forms (idempotent on event + email).

API reference

Request and response schemas for the HubSpot callbacks and the public registration endpoints are listed in the API reference tab, under HubSpot and Events.