Connection lifecycle
- An organizer clicks Connect in Settings > Integrations. The dashboard starts an OAuth link flow (
linkSocialAccount) with provider idhubspot. - 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. - 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 matchingportalIdagainst that metadata. - 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,formscrm.objects.contacts.read,crm.objects.contacts.writecrm.schemas.contacts.read,crm.schemas.contacts.writecrm.lists.read,crm.lists.writecrm.objects.owners.read— owner display names on contactscrm.objects.marketing_events.read,crm.objects.marketing_events.write— Marketing Events + attendancemarketing.campaigns.read,marketing.campaigns.write,marketing.campaigns.revenue.read— campaign container and revenue attributioncrm.objects.deals.read
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:
- Results are limited to registrations on published, non-canceled events. If neither
emailsnorhubspotContactIdsare given, the response is an empty page. no_showmaps tono-show;confirmed,pending, andwaitlistedall surface asregistered;rejectedstaysrejected.ticketTypeispaidwhen the ticket price is greater than zero.- Errors:
401invalid signature,403when the connection needs a reconnect,404when 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 with401. 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-v3andX-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-Signaturewith signature versionv1. The signature is the lowercase hexadecimal SHA-256 hash of the client secret concatenated with the raw request body:SHA-256(clientSecret + rawBody).
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).