---
title: Using HeadQ Events with Custom Event Listeners
description: HeadQ supports custom event listeners, allowing you to hook into key user interactions and extend storefront behavior programmatically. This feature is designed for developers who want to react to user actions such as adding items to the cart, starting checkout, or completing a purchase.
---

[Skip to content](https://support.headq.io/knowledge-base/using-headq-events-with-custom-event-listeners#main-content)

![HeadQ-Png-11](https://support.headq.io/hs-fs/hubfs/HeadQ-Png-11.png?width=100&height=30&name=HeadQ-Png-11.png)

Open main navigation

Close main navigation

 Hello. How can we help you?

- There are no suggestions because the search field is empty.

1. [Support](https://support.headq.io/knowledge-base?hsLang=en)
2. [Settings](https://support.headq.io/knowledge-base/settings?hsLang=en)

# Using HeadQ Events with Custom Event Listeners

HeadQ supports custom event listeners, allowing you to hook into key user interactions and extend storefront behavior programmatically.

This feature is designed for developers who want to react to user actions such as adding items to the cart, starting checkout, or completing a purchase.

### How It Works

You can now listen to HeadQ events directly by using the global `headq.on` function. This method allows you to subscribe to specific events and handle them as needed in your frontend JavaScript.

### Basic Syntax

```
headq.on('<event_name>', (data) => {  // Your custom logic here});
```

#### Supported Events

Below is a complete list of available events and when they are triggered:

| Event Name | Description |
| --- | --- |
| `view_item` | The user opens a product configurator |
| `add_to_cart` | The user adds a product to the cart |
| `add_to_quote_cart` | The user adds a product to the quote cart |
| `view_cart` | The user opens the cart |
| `begin_checkout` | The user starts the checkout process |
| `purchase` | The user finalizes the checkout process and makes a purchase |
| `request_for_quote` | The user requests a quote |
| `calculate_price` | The price was calculated in the configurator |
| `begin_configuration` | The user started the configuration but did not calculate the price |
| `complete_configuration` | The user has completed the configuration and added it to the cart |
| `generate_lead` | The user has done an action that generates a lead to the store |
| `remove_from_cart` | The user has removed the item from the cart |
| `remove_from_quote_cart` | The user has removed the item from the quote cart |

#### Example Event Usage

### `add_to_cart`

Triggered when a user adds a product to the cart.

```
headq.on('add_to_cart', (data) => {  console.log('Product added to cart:', data);});
```

### `begin_checkout`

Triggered when a user starts the checkout process.

```
headq.on('begin_checkout', (data) => {  console.log('Checkout started:', data);});
```

### `purchase`

Triggered when a purchase is completed successfully.

```
headq.on('purchase', (data) => {  console.log('Purchase completed:', data);});
```

#### Best Practices

- Make sure your code does not block the main thread. Use asynchronous functions if needed.
- Always check for the presence of expected fields in the `data` object.
- Avoid placing sensitive or business-critical logic solely inside event listeners.

#### FAQ

**Q: Do I need to enable this feature separately?**

> No, event listeners are available by default when the storefront is running HeadQ.

**Q: Can I remove an event listener?**

> Currently, event removal is not supported. However, you can use flags within your callback logic if you need to conditionally ignore events.

---

 

- [Visual CPQ](https://support.headq.io/knowledge-base/visual-cpq?hsLang=en)
- [Storefront](https://support.headq.io/knowledge-base/storefront?hsLang=en)
- [Product Finder](https://support.headq.io/knowledge-base/product-finder?hsLang=en)
- [Frequently Asked Questions](https://support.headq.io/knowledge-base/frequently-asked-questions?hsLang=en#main-content)

    - [CPQ](https://support.headq.io/knowledge-base/frequently-asked-questions?hsLang=en#cpq)
- [Getting Started](https://support.headq.io/knowledge-base/getting-started?hsLang=en)
- [General](https://support.headq.io/knowledge-base/general?hsLang=en#main-content)

    - [product](https://support.headq.io/knowledge-base/general?hsLang=en#product)
    - [CPQ](https://support.headq.io/knowledge-base/general?hsLang=en#cpq)
- [Reports](https://support.headq.io/knowledge-base/reports?hsLang=en)
- [Integrations](https://support.headq.io/knowledge-base/integrations?hsLang=en#main-content)

    - [Signicat](https://support.headq.io/knowledge-base/integrations?hsLang=en#signicat)
    - [HubSpot](https://support.headq.io/knowledge-base/integrations?hsLang=en#hubspot)
    - [Stripe](https://support.headq.io/knowledge-base/integrations?hsLang=en#stripe)
    - [Salesforce](https://support.headq.io/knowledge-base/integrations?hsLang=en#salesforce)
- [Settings](https://support.headq.io/knowledge-base/settings?hsLang=en)
- [Distributors](https://support.headq.io/knowledge-base/distributors?hsLang=en)

## HeadQ / MVP Digital Oy

HeadQ Support

Copyright © 2025, HeadQ / MVP Digital Oy