HubSpot Integration | blade47/dub Wiki | doc0

Public

HubSpot Integration | blade47/dub Wiki | doc0

Configuration Parameter	Value / Endpoint
Provider Name	`HubSpot`
Auth URL	`https://app.hubspot.com/oauth/authorize`
Token URL	`https://api.hubapi.com/oauth/v1/token`
Redirect URI	`${APP_DOMAIN_WITH_NGROK}/api/hubspot/callback`
Redis State Prefix	`hubspot:oauth:state`
Required Scopes	`oauth`, `crm.objects.contacts.read`, `crm.objects.contacts.write`, `crm.objects.deals.read`, `crm.schemas.contacts.write`

  isTokenValid(token: HubSpotAuthToken) {
    if (!token.created_at) {
      return false;
    }
 
    const buffer = 60 * 1000; // refresh 1 min early
    const expiresAt = token.created_at + token.expires_in * 1000;
 
    return Date.now() < expiresAt - buffer;
  }

Property Label	Internal Name	Data Type	Field Type	Group Name	Form Field Allowed
Dub Click ID	`dub_id`	`string`	`text`	`contactinformation`	`true`
Dub Link	`dub_link`	`string`	`text`	`contactinformation`	`false`
Dub Partner Email	`dub_partner_email`	`string`	`text`	`contactinformation`	`false`

  async updateContact({
    contactId,
    properties,
  }: {
    contactId: number | string;
    properties: Record<string, unknown>;
  }) {
    try {
      const result = await this.fetch(`/objects/contacts/${contactId}`, {
        method: "PATCH",
        body: {
          properties,
        },
      });
 
      return result;
    } catch (error) {
      console.error(
        `[HubSpot] Failed to update contact ${contactId}: ${error}`,
      );
      return null;
    }
  }

  async getContact(contactId: number | string) {
    try {
      const contact = await this.fetch(
        `/objects/contacts/${contactId}?properties=email,firstname,lastname,dub_id,dub_link,dub_partner_email,lifecyclestage`,
      );
 
      return hubSpotContactSchema.parse(contact);
    } catch (error) {
      console.error(
        `[HubSpot] Failed to retrieve contact ${contactId}: ${error}`,
      );
      return null;
    }
  }

    const rawBody = await req.text();
    const signature = req.headers.get("X-HubSpot-Signature");
 
    if (!signature) {
      throw new DubApiError({
        code: "bad_request",
        message: "Missing X-HubSpot-Signature header.",
      });
    }
 
    if (!HUBSPOT_CLIENT_SECRET) {
      throw new DubApiError({
        code: "internal_server_error",
        message: "Missing HUBSPOT_CLIENT_SECRET environment variable.",
      });
    }
 
    const sourceString = HUBSPOT_CLIENT_SECRET + rawBody;
    const expectedHash = crypto
      .createHash("sha256")
      .update(sourceString)
      .digest("hex");
 
    if (!timingSafeCompare(signature, expectedHash)) {
      throw new DubApiError({
        code: "unauthorized",
        message: "Invalid webhook signature.",
      });
    }

    const events = JSON.parse(rawBody) as any[];
    const finalEvents = Array.isArray(events) ? events : [events];
 
    const qstashResponse = await enqueueBatchJobs(
      finalEvents.map((event) => ({
        queueName: "process-hubspot-webhook",
        url: `${APP_DOMAIN_WITH_NGROK}/api/hubspot/webhook/process`,
        deduplicationId: event.eventId,
        method: "POST",
        body: event,
      })),
    );

  try {
    const rawBody = await req.text();
 
    await verifyQstashSignature({
      req,
    });
 
    body = JSON.parse(rawBody);
 
    const { objectTypeId, portalId, subscriptionType } =
      hubSpotWebhookSchema.parse(body);
 
    const installation = await prisma.installedIntegration.findFirst({
      where: {
        integration: {
          slug: "hubspot",
        },
        credentials: {
          path: "$.hub_id",
          equals: portalId,
        },
      },
      include: {
        project: {
          select: {
            id: true,
            stripeConnectId: true,
            webhookEnabled: true,
          },
        },
      },
    });

Design Choice	Benefit	Cost
Batch fan-out via QStash	Isolates failures per event; prevents batch-wide transaction rollbacks	Higher HTTP request volume and dependency on QStash service
Constant-time signature check	Mitigates timing attacks during HMAC signature verification	Requires explicit byte-length handling or utility wrappers
Prisma JSON path credential lookup	Directly queries encrypted portal IDs within stored credential JSON blobs	Couples database schema queries to JSON structure paths (`$.hub_id`)

export function getHubSpotEventAction({
  event,
  settings,
}: {
  event: Pick<
    z.infer<typeof hubSpotLeadEventSchema>,
    "objectTypeId" | "subscriptionType" | "propertyName" | "propertyValue"
  >;
  settings: z.infer<typeof hubSpotSettingsSchema>;
}): "trackLead" | "trackSale" | "skip" {
  const { objectTypeId, subscriptionType, propertyName, propertyValue } = event;
  const { leadTriggerEvent } = settings;
 
  const isCreated = subscriptionType === "object.creation";
  const isPropertyChanged = subscriptionType === "object.propertyChange";

Object Type ID (`objectTypeId`)	Subscription Type (`subscriptionType`)	Property Filter / Condition	Action Result
`0-1` (Contacts)	`object.creation`	None	`trackLead` (Deferred)
`0-1` (Contacts)	`object.propertyChange`	`leadTriggerEvent === "lifecycleStageReached"`	`trackLead`
`0-3` (Deals)	`object.creation`	`leadTriggerEvent === "dealCreated"`	`trackLead`
`0-3` (Deals)	`object.propertyChange`	`propertyName === "dealstage"` && `newDealStage === leadDealStageId`	`trackLead`
`0-3` (Deals)	`object.propertyChange`	`propertyName === "dealstage"` && `newDealStage === closedWonDealStageId`	`trackSale`

    const trackLeadResult = await trackLead({
      clickId: properties.dub_id,
      eventName: "Sign up",
      customerEmail: properties.email,
      customerExternalId: properties.email,
      customerName,
      mode: "deferred",
      workspace,
      source: "hubspot",
      commissionSource: CommissionSource.hubspot,
    });

const trackFinalLead = async ({
  dealId,
  workspace,
  hubSpotApi,
}: {
  dealId: number;
  workspace: Pick<WorkspaceProps, "id" | "stripeConnectId" | "webhookEnabled">;
  hubSpotApi: HubSpotApi;
}) => {
  const deal = await hubSpotApi.getDeal(dealId);
 
  if (!deal) {
    return `No deal found for deal ${dealId}.`;
  }
 
  const { properties, associations } = deal;
 
  const contact = associations?.contacts?.results?.[0];
 
  if (!contact) {
    return `No contact found for deal ${dealId}.`;
  }
 
  const contactInfo = await hubSpotApi.getContact(contact.id);

  const deal = await hubSpotApi.getDeal(objectId);
 
  if (!deal) {
    return `No deal found for deal ${objectId}`;
  }
 
  const { id: dealId, properties, associations } = deal;
 
  if (!properties.amount) {
    return `Amount is not set for deal ${dealId}`;
  }

Schema Model	Property Field	Type	Description
`hubSpotDealSchema`	`id`	`string`	Unique HubSpot deal identifier
`hubSpotDealSchema`	`properties.dealname`	`string`	Name of the CRM deal
`hubSpotDealSchema`	`properties.amount`	`string \| null`	Monetary value of the deal
`hubSpotDealSchema`	`properties.dealstage`	`string`	Current pipeline stage ID of the deal
`hubSpotDealSchema`	`associations.contacts`	`object`	Associated contact references on the deal
`hubSpotSaleEventSchema`	`subscriptionType`	`literal("object.propertyChange")`	Restricted to property change events
`hubSpotSaleEventSchema`	`propertyName`	`literal("dealstage")`	Restricted to deal stage property updates

  await trackSale({
    customerExternalId: customer.externalId!,
    amount: Number(properties.amount) * 100,
    eventName: `${properties.dealname} ${properties.dealstage}`,
    paymentProcessor: "custom",
    invoiceId: dealId,
    workspace,
    metadata: {
      hubspotDealId: dealId,
      hubspotContactId: contactInfo.id,
    },
    source: "hubspot",
    commissionSource: CommissionSource.hubspot,
  });

Setting Field	Type	Default Value	Description
`leadTriggerEvent`	`enum`	`"dealCreated"`	Event that triggers final lead tracking for the contact (`lifecycleStageReached`, `dealCreated`, `dealStageReached`)
`leadLifecycleStageId`	`string \| null`	`null`	Contact lifecycle stage ID representing a qualified lead (used when trigger is `lifecycleStageReached`)
`leadDealStageId`	`string \| null`	`null`	Deal stage ID representing a qualified lead (used when trigger is `dealStageReached`)
`closedWonDealStageId`	`string \| null`	`"closedwon"`	Deal stage ID representing a closed won deal

export const updateHubSpotSettingsAction = authActionClient
  .inputSchema(schema)
  .action(async ({ parsedInput, ctx }) => {
    const { workspace } = ctx;
    const {
      leadTriggerEvent,
      leadLifecycleStageId,
      leadDealStageId,
      closedWonDealStageId,
    } = parsedInput;
 
    if (leadTriggerEvent === "dealStageReached") {
      if (!leadDealStageId) {
        throw new Error("Lead deal stage ID is required.");
      }
 
      if (
        leadDealStageId.toLowerCase() === closedWonDealStageId?.toLowerCase()
      ) {
        throw new Error(
          "Lead deal stage ID must be different from the closed won deal stage ID.",
        );
      }
    }

  async refreshTokenForInstallation(
    installation: InstalledIntegration,
  ): Promise<HubSpotAuthToken> {
    let token = hubSpotAuthTokenSchema.parse(installation.credentials);
 
    token = {
      ...token,
      access_token: decryptOrPassthrough(token.access_token),
      refresh_token: decryptOrPassthrough(token.refresh_token),
    };
 
    if (this.isTokenValid(token)) {
      return token;
    }
 
    const newToken = await this.refreshToken(token.refresh_token);
 
    const credentials = {
      ...newToken,
      created_at: Date.now(),
    };
 
    await prisma.installedIntegration.update({
      where: {
        id: installation.id,
      },
      data: {
        credentials: {
          ...credentials,
          access_token: encrypt(credentials.access_token),
          refresh_token: encrypt(credentials.refresh_token),
        },
      },
    });
 
    return credentials;
  }