# HubSpot

Source: https://gokarla.io/docs/guides/notify/integrations/hubspot

# HubSpot

:::info

The HubSpot integration allows Karla to provide your HubSpot account with triggers of any sort, like shipment notifications or claims.

:::

## Steps

### 1. Open HubSpot & navigate to Settings

Navigate to your HubSpot instance and click on the `Settings` gear icon in the main navigation bar.

![HubSpot 1](/docs/content/docs/notify/integrations/assets/hubspot-app-1.png)

### 2. Create a Private App

In the left sidebar, navigate to `Integrations` → `Legacy Apps`.

Click on `Create`

![HubSpot 2](/docs/content/docs/notify/integrations/assets/hubspot-app-2.png)

Click on `Private`

![HubSpot 3](/docs/content/docs/notify/integrations/assets/hubspot-app-3.png)

Fill the Basic Info

![HubSpot 4](/docs/content/docs/notify/integrations/assets/hubspot-app-4.png)

Add the required scopes

![HubSpot 5](/docs/content/docs/notify/integrations/assets/hubspot-app-5.png)

- **Contact Management**: read contact profiles to match customers
- **Event Tracking**: send custom events to your HubSpot account

These permissions are mandatory to have the minimum notification functionality working:

- `analytics.behavioral_events.send`: allows Karla to send custom events via API
- `crm.objects.contacts.read`: will read contact emails to match delivery events
- `behavioral_events.event_definitions.read_write`: will create `karla_*` custom events

:::note

The exact naming and location of scopes may vary slightly based on your HubSpot version. Look for scopes related to:

- Reading contacts/CRM data
- Sending behavioral or custom events

:::

Skip the `Webhooks` section and click on `Create app` at the top.

![HubSpot 6](/docs/content/docs/notify/integrations/assets/hubspot-app-6.png)

Once you click on `Continue creating`, go to the `Auth` tab, `Show Token` and `Copy` the Access Token.

![HubSpot 7](/docs/content/docs/notify/integrations/assets/hubspot-app-7.png)

### 3. Set up the Private App Access Token in Karla

After selecting the scopes, click on `Create app` and confirm. HubSpot will generate a **Private App Access Token**.

Copy the access token from the generated credentials.

In our [portal](https://portal.gokarla.io/), navigate to `Settings` > `Integrations`, and select `HubSpot`.

![HubSpot Portal 1](/docs/content/docs/notify/integrations/assets/hubspot-portal-1.png)

Paste the `Private App Access Token` and click on `Save`.

![HubSpot Portal 2](/docs/content/docs/notify/integrations/assets/hubspot-portal-2.png)

Once the key has been saved successfully, you can toggle the integration settings.

:::warning Security Note

- Treat this token like a password
- Only share it through secure channels
- You can regenerate the token anytime if needed

:::

## Building HubSpot Workflows

Our HubSpot integration will automatically create custom events prefixed with `karla_` for all delivery journey events.

From there, you can create automation workflows relying on these events to configure your own email flows.

### Workflow Priority Recommendations

To cover the most important delivery journey events, we recommend first creating workflows for the following **event groups**:

1. `karla_shipment_in_transit`
2. `karla_shipment_carrier_delay`
3. `karla_shipment_damaged`
4. `karla_shipment_out_for_delivery`
5. `karla_shipment_delivered_all_events`
6. `karla_shipment_not_picked_up_returned`
7. `karla_shipment_failed_returned`

By creating these 7 workflows you will be able to cover standard events happening for every order (`karla_shipment_in_transit`, `karla_shipment_out_for_delivery`), all delivered cases (`karla_shipment_delivered_all_events`) and the events that hopefully do not happen too often, but where it is most important to be proactive with your customers (`karla_shipment_carrier_delay`, `karla_shipment_damaged`, `karla_shipment_not_picked_up_returned`, `karla_shipment_failed_returned`).

:::info Event Groups vs Webhook Refs

**HubSpot** uses namespaced **event groups** (like `karla_shipment_delivered`) while **webhooks** use **ref patterns** (like `shipments/delivered/SUCCESSFULLY_DELIVERED`). Event groups are business-friendly names that group multiple specific events for easier automation management.

For complete documentation, see: **[Events Reference →](/docs/platform/events/overview)**

:::

### Pickup Reminder Workflow

Create an automated workflow that triggers pickup reminders for packages delivered to parcel shops or lockers that haven't been collected within a specified timeframe.

## Inserting the tracking page link

To include the tracking page link in your HubSpot transactional emails you should use personalization tokens with `order_number` and `zip_code` properties, so that your customers always receive their personalized link:

For emails triggered through HubSpot:

### Karla events

```json title="Karla hosted tracking page"
https://app.gokarla.io/track/slug?orderNumber={{ contact.order_number }}&zipCode={{ contact.zip_code }}&ref=karla
```

```json title="Embedded tracking page"
https://yourshop.com/pages/tracking?orderNumber={{ contact.order_number }}&zipCode={{ contact.zip_code }}&ref=karla
```

### Shipping Confirmation

Triggered by external events from your shop system.

```json title="Karla hosted tracking page"
https://app.gokarla.io/track/slug?orderNumber={{ contact.order_number }}&zipCode={{ contact.shipping_zip }}&ref=karla
```

```json title="Embedded tracking page"
https://yourshop.com/pages/tracking?orderNumber={{ contact.order_number }}&zipCode={{ contact.zip_code }}&ref=karla
```

:::tip

A `slug` is your unique identifier that represents your shop within the Karla system. This is used to properly route tracking information and ensure that shipment data is associated with the correct merchant account.

:::

## Testing the workflows

Once you've set up the workflows and the respective emails it is important you make sure that the integration is working as expected.

In the Email Template Editor go to Preview & Test functionality.

There make sure that in the contact data you see the information from the profiles from your shop and not from Karla's test events. These should be infos like customer name, order number, shipping address etc.

:::warning
You will see this information only after you have integrated your shop and HubSpot with Karla. [More on shop integrations](/docs/guides/shops/overview)
:::

If you want to see how your customers will receive the emails, you can send a test email to your email address.

### Putting the workflows live

After you have tested your workflows, you can put them live upon the agreed go-live date.

:::warning
Make sure you have configured the proper sending settings and have disabled any frequency caps for transactional emails, so that all of your customers receive their shipping updates.
:::

## Event Groups

Karla provides the following **event groups** to your HubSpot instance for building workflows. These are business-friendly groupings that make it easier to create targeted campaigns without dealing with individual event names.

:::info Event Groups vs Webhook Patterns

Event groups are specifically designed for **HubSpot integration** and are different from webhook ref patterns:

- **Event Groups**: Business-friendly names, prefixed by `karla_` (e.g., `karla_shipment_delivered`)
- **Webhook Refs**: Technical identifiers (e.g., `shipments/delivered/SUCCESSFULLY_DELIVERED`)

For complete documentation of all events, ref patterns, and event groups, see: **[Events Reference →](/docs/platform/events/overview)**

:::

### Claims

For any processed claim (e.g. damaged package, package not found...).
See [Claims](https://api.gokarla.io/public/redoc#tag/Claim).

- `karla_claim_created`
- `karla_claim_updated`

### Shipments

For any processed shipment update:

| Event Group                                               | Description                    | Use Case                         |
| --------------------------------------------------------- | ------------------------------ | -------------------------------- |
| `karla_shipment_pre_transit`                              | Package prepared for shipping  | Confirmation emails              |
| `karla_shipment_in_transit`                               | Package moving through network | Journey updates                  |
| `karla_shipment_carrier_delay`                            | Carrier-reported delays        | Proactive communication          |
| `karla_shipment_damaged`                                  | Package damage reported        | Customer service outreach        |
| `karla_shipment_out_for_delivery`                         | Package out for delivery       | Delivery notifications           |
| `karla_shipment_delivered`                                | Successful delivery            | Delivery confirmations           |
| `karla_shipment_delivered_all_events`                     | All delivery variations        | Comprehensive delivery flows     |
| `karla_shipment_delivered_to_letterbox`                   | Delivered to letterbox         | Specific delivery method         |
| `karla_shipment_delivered_to_neighbour`                   | Delivered to neighbor          | Neighbor delivery notification   |
| `karla_shipment_delivered_to_parcel_locker`               | Delivered to parcel locker     | Pickup instructions              |
| `karla_shipment_delivered_to_parcel_shop`                 | Delivered to pickup point      | Pickup notifications             |
| `karla_shipment_delivery_failed`                          | Delivery attempt failed        | Retry communications             |
| `karla_shipment_delivery_failed_address_issue`            | Address problems               | Address correction requests      |
| `karla_shipment_delivery_failed_forwarded_to_parcel_shop` | Forwarded to pickup            | Alternative pickup location      |
| `karla_shipment_delivery_second_attempt`                  | Reattempting delivery          | Second attempt notifications     |
| `karla_shipment_not_picked_up_then_returned`              | Not picked up, returned        | Return notifications             |
| `karla_shipment_refused_then_returned`                    | Customer refused package       | Return processing                |
| `karla_shipment_failed_returned`                          | Package returned to sender     | Return confirmations             |
| `karla_shipment_picked_up`                                | Successfully picked up         | Pickup confirmations             |
| `karla_shipment_lost`                                     | Package lost in transit        | Loss notification and next steps |
| `karla_shipment_delayed_due_to_customer_request`          | Customer requested delay       | Confirmation of delay request    |

### Priority Guide for Workflows

**High Priority** (Essential workflows):

1. `karla_shipment_in_transit` - Keep customers informed
2. `karla_shipment_out_for_delivery` - Delivery readiness
3. `karla_shipment_delivered` - Delivery confirmation
4. `karla_shipment_carrier_delay` - Proactive communication
5. `karla_shipment_delivered_all_events` - Any delivery event

**Medium Priority** (Enhanced experience):

1. `karla_shipment_delivered_to_parcel_shop` - Pickup instructions
2. `karla_shipment_delivery_failed` - Retry coordination
3. `karla_shipment_damaged` - Customer service escalation

**Lower Priority** (Edge cases):

1. `karla_shipment_not_picked_up_then_returned` - Return processing
2. `karla_shipment_failed_returned` - Return confirmation
3. `karla_claim_created` - Claims management

## Common Use Cases

### Post-Delivery Review Request

**Event Group**: `karla_shipment_delivered`
**Timing**: 2-3 days after delivery
**Content**: Thank you message + review request

### Pickup Reminder

**Event Group**: `karla_shipment_delivered_to_parcel_shop`
**Timing**: Immediate + daily reminders
**Content**: Pickup location, hours, deadline

### Delivery Issue Resolution

**Event Group**: `karla_shipment_delivery_failed`
**Timing**: Immediate
**Content**: Failed reason, next steps, support link

### Proactive Delay Communication

**Event Group**: `karla_shipment_carrier_delay`
**Timing**: As soon as delay detected
**Content**: New ETA, apology, compensation if applicable

## Best Practices

### 1. Email Content Guidelines

- **Be Specific**: Reference the exact delivery status
- **Include CTAs**: Add tracking links and next steps
- **Personalize**: Use customer and order data available from the event
- **Mobile-Optimize**: Most tracking emails are read on mobile

### 2. Testing Recommendations

1. Test each event group workflow separately
2. Verify personalization tokens populate correctly
3. Check email rendering across devices
4. Monitor delivery rates and engagement

## Troubleshooting

### Events Not Triggering Emails

1. Verify event group name matches exactly (case-sensitive)
2. Check integration credentials are active
3. Confirm workflow is published in HubSpot
4. Test with Karla test events

### Missing Data in Emails

1. Ensure all personalization tokens match the event properties
2. Check token syntax (`{{ contact.field_name }}`)
3. Verify contact property mapping

### Email Delivery Issues

1. Check HubSpot sending logs
2. Verify customer email addresses
3. Review spam folder placement
4. Check domain authentication (SPF/DKIM)

### Cannot Find Private Apps Option

- Verify you have **Super Admin** permissions
- Check if your HubSpot subscription tier supports Private Apps
- Try looking under Settings → Integrations → API Key (for legacy setups)
- Contact HubSpot support to enable Private Apps for your account

### Token Not Working

- Ensure you copied the complete token
- Verify the selected scopes match the requirements above
- Check that you're using your production account, not a test account
- Confirm the Private App is active (not deactivated)

## Security Best Practices

- **Rotate tokens periodically** - You can regenerate the token in HubSpot without breaking the integration (just update it in Karla)
- **Monitor app activity** - HubSpot provides logs of API calls made by your Private App
- **Limit scopes** - Only grant the minimum required permissions listed above
- **Use secure channels** - Never share tokens via email or public channels

## Support

- **Karla Integration Support**: support@gokarla.io
- **HubSpot Technical Support**: Refer to your HubSpot account manager
- **Technical Documentation**: [Karla Events](/docs/platform/events/overview)

## Next Steps

1. Identify which event groups align with your communication strategy
2. Create workflows for your priority events
3. Design and test email templates
4. Monitor performance and optimize