HubSpot setup guide

Agents look up customers and deals and keep your records tidy.

Ways to connect

Company admins connect apps, on the Integrations page in Everdeck: open HubSpot, choose one of the ways below, follow its steps and fill in its fields. Everdeck checks what you enter before it saves anything, and asks you to confirm it’s you (your second factor) before you type any secret. How connecting works.

HubSpot can be connected 2 ways. Where there’s a key or token to paste, that’s usually the quickest.

Service key or private app token

API key.

1. Sign in to HubSpot as a super admin (or a user with the Developer tools access permission).
2. Open Development, then Keys > Service keys, and click Create service key.
3. Name it (for example "Everdeck"), click Add new scope, tick the scopes listed below and click Update. Then click Create and confirm in the dialog.
4. Open the key, click Show, then Copy, and paste it here. Leave the client secret empty. Triggers (starting work when a contact is created or a deal changes) need a legacy private app instead, since service keys can't receive webhooks:
5. Set the trigger up on the Intake page and copy the address it gives you.
6. In HubSpot open Development > Legacy apps, click Create legacy app and choose Private. Name it and, on the Scopes tab, add the scopes listed below.
7. On the Webhooks tab paste the address as the Target URL. Click Create subscription: for contact_created choose Contacts and Created; for deal_updated choose Deals, Created and Property changed (for example dealstage and amount). Then click Create app.
8. On the Auth tab, copy the access token into the access token field here, click Show secret and copy the client secret into Private app client secret. An app sends all its subscriptions to its one Target URL, so it serves one trigger: for the other one, create a second legacy private app and connect HubSpot again with it. A token connection made before triggers existed needs the client secret added before its trigger can receive anything.

Field	What to enter
Service key or private app access token	A secret: Everdeck saves it encrypted and never shows it again. Where to find it.
Private app client secret (optional, for triggers)	A secret: Everdeck saves it encrypted and never shows it again. Only for triggers: the legacy private app's client secret (its Auth tab, Show secret). HubSpot signs its webhooks with it. Leave it empty for a service key.

The scopes Everdeck asks for:

• 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.tickets.read
• crm.objects.tickets.write
• crm.objects.owners.read

Disconnecting deletes the credentials Everdeck saved, but Everdeck can't revoke them: the key, token or password itself keeps working at HubSpot until you delete or rotate it there.

Your HubSpot app (OAuth)

Your OAuth app.

This way signs in with an OAuth app you create for HubSpot, as its steps describe: Everdeck never uses an app of its own. Register this redirect URI with your app:

https://everdeck.io/api/oauth/callback

Then save the app’s client ID and secret in Everdeck, on the connect page or under OAuth apps, and sign in.

1. HubSpot creates OAuth apps with its CLI only. Install it (npm install -g @hubspot/cli) and run hs account auth to sign in to your HubSpot account.
2. Run hs project create, choose App, set distribution to private and authentication to oauth.
3. In the project's app-hsmeta.json set "redirectUrls": ["https://everdeck.io/api/oauth/callback"] and list the scopes below in "requiredScopes" (HubSpot adds the oauth scope itself), then run hs project upload.
4. In HubSpot open Development > Projects, click the project, then the app. On the Distribution tab click Add approved account(s) and select your HubSpot account. On the Auth tab copy the Client ID and Client secret (under Client credentials) here.
5. Click Connect and approve the install as a super admin. Triggers (starting work when a contact is created or a deal changes): set the trigger up on the Intake page and copy the address it gives you. Add a webhooks component to the project (src/app/webhooks/webhooks-hsmeta.json) with settings.targetUrl set to that address and a crmObjects subscription: object.creation for objectType contact (contact_created), or object.creation and object.propertyChange (with a propertyName such as dealstage) for objectType deal (deal_updated). Run hs project upload again. HubSpot signs its webhooks with the app's client secret, which this connection already holds. An app sends every subscription to its one targetUrl, so it serves one trigger: for the other one, use a second app and connect HubSpot again with it. An app approved for several HubSpot accounts sends all their events there; the trigger takes only those of the account you connect. A connection signed in before triggers existed doesn't know its account yet: click Reconnect on its page before setting a trigger up, or the trigger refuses every delivery.

The scopes Everdeck asks for:

• oauth
• 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.tickets.read
• crm.objects.tickets.write
• crm.objects.owners.read

When you disconnect, Everdeck asks HubSpot to revoke the sign-in, then deletes the tokens it saved.

What agents can do

An agent uses an action only when its charter grants it, on the agent’s Tools tab, where you choose whether each one runs by itself (Auto), asks first or never runs. Each action has a risk tier: tier 3 actions, which customers or the public see, ask first unless you choose otherwise, and tier 4 actions (money, deleting things, access) always need a person. How tools and tiers work.

Actions marked Reads outside content return things people outside your company may have written. Agents treat what they read as information, never as instructions, and their riskier actions later in the same session need approval.

• Search CRM recordsTier 0 · ReadReads outside contenthubspot_search_records

  Search contacts, companies, deals, tickets, tasks or notes. Use query for free text (contacts match name, email, phone and company; companies match name, domain, website and phone; deals match deal name, pipeline, stage, description and type; tickets match subject, content, stage, category and ticket id; tasks match subject and body; notes match the body) and/or filter_groups for exact property filters. Returns record ids and the requested properties. Up to 200 per page, 10,000 per query; newly written records can take a few seconds to appear.

• Read a recordTier 0 · ReadReads outside contenthubspot_get_record

  Read one contact, company, deal, ticket, task or note by id, with chosen properties and the ids of linked records (for example associations "companies,deals" on a contact).

• Create a recordTier 2 · ReversibleReads outside contenthubspot_create_record

  Create a contact, company, deal or ticket, optionally linked to existing records. Deals need dealname, pipeline and dealstage (stage ids from list_pipelines); tickets need subject, hs_pipeline and hs_pipeline_stage. Email is a contact's unique identifier, so search for it first: creating a contact with an email that already exists fails.

• Update a recordTier 2 · ReversibleReads outside contenthubspot_update_record

  Change properties on a contact, company, deal, ticket, task or note. Send only the properties to change; an empty string clears a value. Move a deal by setting dealstage; complete a task by setting hs_task_status to COMPLETED.

• Link two recordsTier 2 · ReversibleReads outside contenthubspot_associate_records

  Link two existing records with HubSpot's default (unlabeled) association, for example a contact to a company or a deal to a contact.

• Log a noteTier 2 · Reversiblehubspot_create_note

  Add a note to the timeline of one or more records (visible to the HubSpot team, not to the customer). Link it with associations; at least one is needed for it to show on a record.

• Create a taskTier 2 · ReversibleReads outside contenthubspot_create_task

  Create a to-do for a HubSpot user (call, email or general to-do) with a due date, linked to the records it is about. The assignee sees it in their task queue.

• List pipelines and stagesTier 0 · ReadReads outside contenthubspot_list_pipelines

  List the deal (or ticket) pipelines with their stage ids and labels. Use the ids for pipeline and dealstage when creating or moving deals.

• List ownersTier 0 · ReadReads outside contenthubspot_list_owners

  List HubSpot users who can own records, with the owner id used in hubspot_owner_id. Filter by email to find one person.

• List propertiesTier 0 · ReadReads outside contenthubspot_list_properties

  List the properties of an object (internal name, label, type and dropdown options), including custom ones. Use before creating or filtering on unfamiliar fields.

What can start work

These events from HubSpot can become tasks for your agents through Intake. How Intake works.

A contact was created (HubSpot subscription contact.creation, or object.creation for contacts). Needs a legacy private app or your own HubSpot app: service keys can't receive webhooks.

Connect HubSpot first. Then, on the Intake page, open Webhooks and sources, find the connection under Connections without an address yet and select Get its URL. Give that address to HubSpot as the setup steps above describe: Everdeck shows it only once. Then, on the Rules tab, select New rule to say which requests become tasks and who gets them.

A deal was created or one of its subscribed properties changed (deal.creation, deal.propertyChange, for example dealstage or amount, or object.creation and object.propertyChange for deals). Needs a legacy private app or your own HubSpot app.

Connect HubSpot first. Then, on the Intake page, open Webhooks and sources, find the connection under Connections without an address yet and select Get its URL. Give that address to HubSpot as the setup steps above describe: Everdeck shows it only once. Then, on the Rules tab, select New rule to say which requests become tasks and who gets them.

Testing, problems and disconnecting

Everdeck checks the connection when you save it. On the connection’s page in Integrations, Test checks it again at any time.

If HubSpot later refuses the connection, for example because a key was deleted or a sign-in expired, the connection shows Needs attention on the Integrations page and the people who manage connections are told. Agents can’t use it until a company admin fixes it with Edit or Reconnect.

To stop agents using HubSpot, open the connection and select Disconnect. Agents stop using it at once and its saved credentials are deleted. What else happens depends on how it was connected: each way above says.