Home Helpdesk Integrations | HubSpot HubSpot | New transfer logic — Custom Events and Workflows

HubSpot | New transfer logic — Custom Events and Workflows

Last updated on Sep 09, 2026

1. What changed in the HubSpot handover logic?

In February 2026, HubSpot released new capabilities that allow us to evolve the logic for transferring tickets to N2. With that, we migrated the handover flow to this new approach, making the feature more resilient, traceable and observable.

The main improvements this evolution brings:

  • Greater resilience: the flow now runs entirely through official HubSpot APIs and automations, reducing points of failure.

  • Traceability: every transfer generates auditable events directly on the platform, making it easier to investigate any occurrence.

  • Observability: we can monitor more precisely how many transfers are completed successfully and quickly identify any deviation.

2. How does the new handover logic work?

When ClaudIA decides to hand the ticket over to N2, the system now:

  1. Looks up the ID of the ticket associated with the conversation in HubSpot.

  2. Fires a Custom Event through the official HubSpot API, referencing that ticket.

  3. A Workflow configured in HubSpot is triggered automatically when it receives that event.

  4. The Workflow performs the transfer, assigning the ticket to the configured N2 agent or team.

No extra authentication is required — the whole flow goes through the platform's official APIs and automations.

3. Do I need to do anything in my HubSpot?

Yes. For the new flow to work, you need to create the following in your HubSpot:

  • 1 ticket creation notification Workflow — sends the ticket ID to our system the moment it is created (one per integration).

  • 1 Custom Event per handover flow — receives the signal from ClaudIA to start the transfer.

  • 1 handover Workflow based on that event, per handover flow — performs the assignment to the N2 agent or team.

⚠️ Customers using the Inbox version (instead of Helpdesk) need two additional workflows. See section 7 for details.

4. Why do we need a ticket creation event sent to our webhook?

To trigger the handover correctly, the system needs to know the HubSpot ticket ID (hs_ticket_id) associated with the ongoing conversation.

HubSpot does not provide an official API method to obtain the ticket ID from a conversation ID (threadId). In other words: when ClaudIA is handling a conversation and needs to hand the ticket over, there is no way to simply query the HubSpot API and ask "which ticket is associated with this conversation?" in a direct and reliable way.

To solve this, we use an event sent by HubSpot itself to our webhook at the moment the ticket is created. That event carries the conversation's threadId and the hs_ticket_id of the newly created ticket, allowing us to store that association on our side and use it during the handover.

⚠️ Without this event, the system cannot reliably identify the correct ticket and the handover via custom event may fail.

4.1. How to configure the ticket creation notification Workflow

  • Go to "Automações → Fluxos de Trabalho" (Automation → Workflows).

    • Create a Ticket-based workflow.

  • Configure the trigger: "Quando um ticket é criado" (When a ticket is created).

  • Add the "Enviar webhook" (Send a webhook) action and configure it with the URL provided by Cloud Humans.

  • The payload must include the ticket ID (hs_ticket_id) and the ID of the associated conversation (threadId).

  • Turn the Workflow on.

This workflow only needs to exist once per integration, no matter how many handover flows you have.

5. How to configure the handover Custom Event in HubSpot

The Custom Event is the trigger Cloud Humans uses to tell HubSpot that a handover should happen.

5.1. Create the Custom Event

  • Go to "Configurações → Gerenciamento de dados → Eventos personalizados" (Settings → Data Management → Custom Events).

  • Click "Criar evento personalizado" (Create custom event).

  • Give the event a clear name (e.g.: transbordo_para_n2).

  • Add the required property: objectId (type: Number).

  • Save the event.

⚠️ After creating the event, copy the internal name generated by HubSpot (format pe12345_nome_do_evento) and send it to the Cloud Humans team — it is required for the configuration on our side.

5.2. Send the event's internal name to Cloud Humans

Once created, send to your Customer Success contact:

  • The internal name of the Custom Event you created.

  • Confirmation that the event is active.

6. How to configure the handover Workflow in HubSpot

The Workflow is the automation responsible for moving the ticket to the human team when the handover event is received.

6.1. Create the Workflow

  • Go to "Automações → Fluxos de Trabalho" (Automation → Workflows).

  • Click "Criar fluxo de trabalho" (Create workflow) and select "Baseado em evento personalizado" (Custom event-based).

  • Select the event created in section 5.

6.2. Configure the assignment action

  • Add the "Atribuir proprietário do ticket" (Set ticket owner) action.

  • Select the target N2 agent or team.

  • You must enable the "Substituir qualquer proprietário do ticket existente" (Overwrite any existing ticket owner) option.

⚠️ Without enabling this option, tickets that already have an owner assigned will not be transferred.

6.3. Turn the Workflow on

  • Save and click "Ativar" (Turn on).

7. Additional configuration for customers using the Inbox version

The new handover logic works with the HubSpot Helpdesk version, which already automatically associates a ticket with each conversation. Customers still using the Inbox version need to configure two additional workflows to guarantee that association.

⚠️ In the Inbox version, each conversation must have at most one associated ticket. If there is more than one ticket per conversation, the system will not be able to identify which one to use and the handover may fail.

7.1. Workflow: create a ticket when a conversation starts

  • Go to "Automações → Fluxos de Trabalho" (Automation → Workflows).

  • Create a Conversation-based workflow.

  • Configure the trigger to create the ticket as soon as the conversation reaches ClaudIA — or, if you already have a flow that creates it, that flow must be adjusted to send us the creation webhook.

  • Add the "Criar ticket" (Create ticket) action and configure the required fields (pipeline, initial stage, etc.).

  • Turn the Workflow on.

7.2. Workflow: associate the conversation with the ticket owner

  • Create a second conversation-based workflow.

  • Configure the trigger: Ticket (Associated Object)".

    • The last message is a thread comment is equal to True

    • Ticket owner has ever been any of Claudia Cloud Humans

  • Add the "Revezar registro para o proprietário" (Rotate record to owner) action and choose your transfer options.

  • Turn the Workflow on.

8. What if I have more than one handover flow?

Operations with multiple N2 destinations (e.g.: technical support, finance, sales) need one Custom Event and one Workflow for each handover flow.

  • Repeat the configurations in sections 5 and 6 for each flow.

  • Send all the internal names of the events you created to the Cloud Humans team.

The ticket creation notification Workflow (section 4) does not need to be duplicated — it is unique per integration.

9. Using an "infinite ticket" — re-enrollment in the Workflow

Some customers use the infinite ticket setup, where the same ticket is reused across multiple interactions over time. In that scenario, the handover flow may need to be triggered more than once for the same ticket.

By default, HubSpot Workflows do not allow the same record to be enrolled again once it has already gone through the flow. To enable this:

  • Open the handover Workflow.

  • Go to Settings (gear icon).

  • Enable the "Permitir que registros sejam reinscritos" (Allow records to re-enroll) option.

You need to talk to our team if your operation uses an infinite ticket and whether this setting applies to your case.