Clickstream webhooks send shopper actions from your Tapcart app to an HTTPS endpoint you control as they happen. Each event is one action, such as opening the app, viewing a product, adding to cart, starting checkout, or completing a purchase.

You connect the webhook in the Tapcart dashboard. You do not need an API key, and you do not need to email Tapcart your URL.

In this article:

What clickstream webhooks are (and are not)
How events are delivered
How to connect a webhook in your dashboard
Events you can receive
What each payload includes
Things to know before you go live

What clickstream webhooks are

Use clickstream webhooks when you want Tapcart to push live app events into your own system. Common setups include a data warehouse, a middleware service, or a third-party tool that accepts webhooks.

This is different from other Tapcart data options:

Insights in the dashboard: aggregated app reporting you can view in Tapcart. No webhook required.
Insights API: a separate API for pulling aggregated metrics (for example, historical push campaign performance). That requires an API key from Tapcart Support. It does not stream individual shopper events.
Analytics integrations (Firebase, Klaviyo, and others): send events into those platforms. Use those integrations when you want data in that tool, not a custom endpoint.
Older Insights Stream / mobile event webhooks: deprecated. If you still receive that older payload format, switch to clickstream. Clickstream includes richer event data, more event types, and dashboard setup.

Webhooks only send events from the moment you connect them. They do not backfill historical data.

How events are delivered

When a shopper takes an action in your app, Tapcart sends an HTTP POST to your HTTPS endpoint. The body is JSON. Each request is one event for one shopper action.

Every payload uses the same top-level shape:

event: the event name (for example, productViewed or purchaseCompleted)
data: details specific to that action (product, cart, order, search query, and so on)
properties: device and session context included on every event (app ID, device ID, OS, timestamp, logged-in customer when available)
mp_metadata: identifiers for the event and session. Use mp_event_id if you need to ignore duplicate deliveries.

Requests also include headers you can use to filter before parsing the body:

appid
eventtype
deviceid
eventid

How to connect a webhook

Before you start

Have an HTTPS URL ready that can accept POST requests. A dedicated route is typical, for example:

https://yourcompany.com/tapcart_webhooks

Your endpoint should:

Use HTTPS (not HTTP)
Accept POST requests with a JSON body
Respond with a 200 status when the event is received
Be reachable on the public internet (Tapcart cannot post to localhost or a private network)

In the Tapcart dashboard

Open your Tapcart dashboard and go to Settings.
Open the Webhooks section.
Turn the feature on.
Enter your HTTPS endpoint.
Choose which events to send. You can select all events, or only the ones you need, so you can limit volume.
Save.

To confirm it is working, trigger an event in a live or preview app (for example, open a product) and check that your endpoint receives a POST.

Events you can receive

You can subscribe to all of these, or a subset:

Event	When it fires
`applicationInstalled`	First open after install
`applicationOpened`	App opened or brought to the foreground
`pageView`	Shopper viewed a screen that does not have a more specific event
`collectionViewed`	Shopper opened a collection
`productViewed`	Shopper opened a product page
`search`	Shopper submitted a search
`cartAdd`	Item added to the Shopify cart
`cartRemove`	Item removed from the cart
`cartUpdated`	Cart changed in another way (quantity, discount, and similar)
`checkoutCreated`	Shopper tapped checkout
`purchaseCompleted`	Shopper placed an order
`loggedIn` / `loggedOut`	Shopper signed in or out
`pushOpened`	Shopper opened a Tapcart push notification
`wishlistItemAdded`	Shopper saved an item to a Tapcart wishlist

For field-by-field schemas and example JSON, see the clickstream webhook reference.

What each payload includes

On every event (in properties):

Your Tapcart app ID
A stable device ID
Whether the shopper is logged in, and their Shopify customer ID when they are
OS (ios or android), app version, and timestamp
Locale details when the device provides them (country, language, timezone)

On commerce events (cart, checkout, purchase, product view), data often includes Shopify catalog details such as product IDs, variant IDs, prices, and cart line items. Many IDs use Shopify's GID format, for example gid://shopify/Product/123. The numeric ID is the last part of that string.

purchaseCompleted is the conversion event. It includes the Shopify order identity, purchased line items, and a price breakdown (subtotal, shipping, taxes, total, discounts).

Things to know before you go live

No historical backfill. Events start when the webhook is connected. For past reporting, use Insights in the dashboard or the Insights API.
Choose only the events you need. High-traffic apps can generate a large volume of pageView and applicationOpened events.
Deduplicate with mp_event_id. Treat that ID as unique if the same event could arrive more than once.
Respect tracking opt-out. Events can still be delivered when trackingEnabled is false (for example, after an iOS App Tracking Transparency decline). Honor that flag in your processing if you use the data for advertising or analytics.
Anonymous vs logged-in shoppers. Before login, identity is device-based. After loggedIn, later events include the Shopify customer ID.
This is not the Insights API. If you need to pull daily dashboard stats or historical push campaign metrics into a report, ask Tapcart Support for Insights API access. Connecting a webhook will not return that aggregated history.

Connecting Clickstream Webhooks