HubSpot

Connect a HubSpot account to run your sales flow from metamorphOS. metamorphOS reads and writes contacts, companies and deals, links them to each other, adds products to deals as line items, creates quotes, moves deals through their pipeline, and starts processes when HubSpot reports a new contact, company or deal, or a changed property.

Screenshots are pending.

What you can do

• Contacts, companies, deals: create, update, look up, and search by property or free text.
• Links between records: link a deal to its contact, company, line items or quote, and list what a record is linked to.
• Pipelines and owners: read your deal pipelines and their stages, and the users who can own records. Processes read stage and owner ids from HubSpot; you never type them in.
• Products and line items: find products in your product library and add them to a deal with a quantity and price.
• Quotes: create a draft quote for a deal from one of your quote templates, publish it, and read its public link.
• Notes: log a note on a record’s timeline.
• Events: start a process when a contact, company or deal is created, or when a contact or deal property you choose changes (for example a deal’s stage).

Before you start

You need a HubSpot account and a super admin login in it: only super admins can create private apps. Products, line items and quotes need a HubSpot subscription that includes them.

Each HubSpot account connects with a private app of its own, created in that account.

Set up HubSpot

1. Create a private app. In your HubSpot account, go to Development → Legacy apps, choose Create legacy app, then Private. Name it, for example metamorphOS. HubSpot lists private apps under legacy apps; they remain supported.
2. Add the scopes. On the Scopes tab, choose Add new scope and tick exactly these:
   • crm.objects.contacts.read, crm.objects.contacts.write
   • crm.objects.companies.read, crm.objects.companies.write
   • crm.objects.deals.read, crm.objects.deals.write
   • crm.objects.products.read
   • crm.objects.line_items.read, crm.objects.line_items.write
   • crm.objects.quotes.read, crm.objects.quotes.write
   • crm.objects.owners.read
3. Create the app. Choose Create app and confirm.
4. Copy the access token. On the app’s Auth tab, choose Show token, then Copy. The same tab holds the app’s client secret, which you need to receive events.

Connect in metamorphOS

Activate the HubSpot connector from the marketplace and add an account. Choose API key or token and paste the private app’s access token.

To check the account, run List Owners: it needs no input and returns the users of your HubSpot account. A token that lacks a scope gets a permission error from the first action that needs it; add the scope to the private app.

If you rotate the token in HubSpot, paste the new one into the account.

Receive HubSpot events

HubSpot sends all events of a private app to one address. Set it once and add a subscription for each event your processes start on.

1. On the private app’s Webhooks tab, set the Target URL to the address metamorphOS shows for this connector.

2. Create the subscriptions you need:

   Event	Subscription
   Contact created	contact.creation
   Contact property changed	contact.propertyChange, with the property to watch
   Company created	company.creation
   Deal created	deal.creation
   Deal property changed	deal.propertyChange, with the property to watch, e.g. dealstage

3. Activate the subscriptions.

4. Store the client secret on the account. HubSpot signs each delivery with the private app’s client secret (Auth tab, Show secret). Paste it as the account’s webhook signing secret in metamorphOS.

5. Deploy the process after the secret is stored. A process picks up the secret when it is deployed. If you store or change the secret later, redeploy the process.

metamorphOS rejects any delivery whose signature does not match. If you rotate the client secret in HubSpot, store the new one and redeploy.

Private apps built as projects on HubSpot’s developer platform do not support webhook subscriptions. Create the private app under Legacy apps as described above.

Good to know

• Pipeline and stage ids differ between HubSpot accounts. Use List Pipelines in a process: it also names the first pipeline’s open, closed won and closed lost stage.
• A line item belongs to one record. Add separate line items to a deal and to its quote.
• HubSpot refuses a second contact with the same email address.
• Search finds new or changed records after a short indexing delay.
• Custom properties can be written through the properties field of every create and update. To read one, name it in properties on the read.
• Orders, tickets, custom objects, and marketing, email and file features are not included.