How to send Knock data to Heap

This guide covers how to use our Heap extension to send Knock's normalized notification data into Heap to forward on to your data warehouse or other tools where you run data analysis, such as Amplitude or Mixpanel.

Once the extension is enabled, Knock automatically passes a stream of track events to Heap (e.g. Notification delivered, Notification seen, Notification read) which you can then use in your downstream tools.

Enterprise plan feature. The Knock Heap extension is only available on our Enterprise plan.

Getting started

Knock uses the Heap Bulk Track endpoint to send events to your Heap project environments. Each Heap project has a group of environments, and each of them has an environment id associated with it that Knock can use to push events into Heap.

A best practice is to create a separate Heap environment for each Knock environment from which you plan to collect events.

  1. Create a new Heap project with environments in your Heap account. You need to create one Heap environment for each Knock environment from which you plan to collect events
    1. Log into your Heap dashboard, click Account > Manage > Projects, and then choose your main project
    2. A list of environments will appear on your right side of the screen. By default Heap creates two environments (Production and development), but you can create more if you need it
    3. Each environment has an id that will be used by Knock to send events to the given environment
  2. Visit the Integrations page in your Knock account and go to the Extensions Tab
  3. Find the Heap extension and click "Connect"
  4. In the modal that appears, enter the Heap environment id for each environment you want to configure. Leave the field blank to disable writing events from that environment
  5. Once you click save, events will begin flowing from that environment to Heap
Heap extension configuration example

Label custom events

Heap requires the labeling of custom received events from Knock before their use.

  1. From your Heap dashboard, navigate to Data > Labeled Events and click on "Label event" or Property > Event
  2. Select "Custom" under the source filter and choose one of the previously received events that you want to label
  3. Add a name for the given event and click on "Label event"
  4. Finally, click on "Verify event"
  5. Once these steps are completed, the validated event will be ready for analysis and usage in your charts

You can find more information about custom events and how to use them in the Heap documentation

Heap has an expected latency for custom track events, which is typically less than 1 hour. Bear in mind that events may not immediately appear for labeling.

Events sent to Heap

When connected, Knock will forward the following Track events to Heap.

Notification sentOccurs when a message is successfully sent to a channel provider.
Notification deliveredOccurs when a message is marked as delivered to the user by the provider. This is only available on email providers with delivery tracking enabled.
Notification undeliveredOccurs when a message delivery attempt fails permanently. Delivery will not be retried.
Notification seenOccurs when a message is seen by its recipient.
Notification unseenOccurs when a message is marked unseen by the recipient.
Notification readOccurs when a message is marked as read by its recipient.
Notification unreadOccurs when a message is marked unread by the recipient.
Notification archivedOccurs when a message is archived by its recipient.
Notification unarchivedOccurs when a message is unarchived by its recipient.
Notification clickedOccurs when a link is clicked by the message recipient. This is only available when Knock link tracking is enabled.
Notification interactedOccurs when a recipient interacts with a message. This is only available when Knock link tracking is enabled.

Event schema

Knock uses the Heap Bulk track endpoint for sending event data to Heap. You can find an example payload of what you can expect from Knock events coming into Heap below.