How to configure your Webhook?

You will create an HTTPS endpoint on your app as a webhook receiver, and specify that endpoint's URL as the webhook subscription's endpoint.

This generated URL must be able to accept HTTP POST requests. For example, your domain is

https://mycompanysite.com

A common method merchant's may use is a route to a dedicated webhook endpoint. An example of a route to that webhook endpoint is:

@app.route('/tapcart_webhooks', methods=['POST'])

Then the specified URL should combine your domain and the webhook endpoint

https://mycompanysite.com/tapcart_webhooks

How do I send my URL to Tapcart?

Once the URL has been specified with a domain and webhook endpoint that can receive POST requests, you will need to reach out to the Tapcart team via email. We will take the URL and then subscribe the merchant to a dedicated topic to receive POST requests.

Please email the URL to: developertools@tapcart.co

How will I know data has successfully been sent?

The following messages represent the standard error codes your server should send after Tapcart's attempted POST requests are sent to the webhook endpoint:

Code	Description
200	Successful Request
400	Invalid Request
401	Unauthorized Request
403	Forbidden
429	Throttling errors
422	Custom errors
500–511	Server errors

In the event you see a 400 or 500 response, Tapcart webhooks will go through a process of retrying the event in order to complete for 5 minutes. If the event still fails to process, Tapcart will end retrying the event.

Payload Structure

Upon receiving a successful 200 POST request from the webhook, an individual payload will be received in JSON format.

This event payload will include a single event performed by a single user. The webhook streams data as it's received and in its entirety.

Guaranteed Fields (All Events)

The following fields are present on every mobile app event payload:

Field	Type	Description
`event_type`	string	The name of the event (e.g. `AppOpened`, `ProductViewed`).
`event_id`	string	Unique identifier for the event.
`app_id`	string	Unique merchant identifier.
`device_id`	string	Unique device identifier.
`timestamp`	number	Event timestamp in epoch milliseconds.
`device_properties`	object	Device information. See Device Properties.
`app_properties`	object	App configuration data. See App Properties.
`shopify_properties`	object	Shopify user data. See Shopify Properties.
`session_properties`	object	Session data. See Session Properties.
`event_properties`	object	Event-specific data. Contents vary by `event_type`. See Event Properties.

Device Properties

Fields present on every event:

Field	Type	Description
`os`	string	Operating system (e.g. `ios`, `Android`).
`os_version`	string	OS version (e.g. `26.3.1`, `18.7.7`).
`manufacturer`	string	Device manufacturer (e.g. `Apple`).
`country`	string	Two-letter country code (e.g. `US`).
`locale`	string	Locale code (e.g. `en`, `es`).

App Properties

Fields present on every event:

Field	Type	Description
`app_id`	string	Unique merchant identifier.
`app_version`	string	App version (e.g. `7.9`).
`os_version`	string	OS version.
`tapcart_build`	string	Tapcart build version (e.g. `20.17.1`).
`active_feature_experiments`	string	JSON-encoded string containing active feature flag experiments.

Shopify Properties

Fields present on every event:

Field	Type	Description
`shopify_user_id`	string \| number \| null	Shopify customer ID. `null` when user is not identified.
`logged_in`	boolean	Whether the user is logged in.

Session Properties

Fields present on every event:

Field	Type	Description
`session_id`	string	Unique session identifier.
`source`	string	Session source (e.g. `direct`).

Event Properties

The contents of event_properties vary by event_type. This object is always present but its fields are event-specific. See Event Properties by Type for details.

Example Payload (Standard Format)

The majority of events use this structure. Below is an AppOpened event:

{
  "app_id": "UNIQUE MERCHANT ID",
  "device_id": "UNIQUE DEVICE ID",
  "event_id": "UNIQUE EVENT ID",
  "timestamp": 1776123343508,
  "device_properties": {
    "manufacturer": "Apple",
    "os": "ios",
    "os_version": "26.3.1",
    "country": "US",
    "locale": "en"
  },
  "app_properties": {
    "app_id": "UNIQUE MERCHANT ID",
    "app_version": "7.9",
    "os_version": "26.3.1",
    "tapcart_build": "20.17.1",
    "active_feature_experiments": "[{\"name\": \"feature-flag-name\", \"value\": true}]"
  },
  "shopify_properties": {
    "shopify_user_id": "1234567890",
    "logged_in": true
  },
  "session_properties": {
    "session_id": "UNIQUE SESSION ID",
    "source": "direct"
  },
  "event_properties": {},
  "event_type": "AppOpened"
}

Extended Format

Some events include additional fields beyond the standard format. The CustomBlockViewed event is a known example that includes the full extended payload.

Additional Top-Level Fields

Field	Type	Description
`metadata`	object	Contains `schema_id` identifying the event schema version.
`timestamp_iso`	string	ISO 8601 formatted timestamp (e.g. `2026-04-13T17:03:56.014-07:00`).

Additional Device Properties

Field	Type	Description
`ip`	string	User's IP address.
`model`	string	Device model identifier (e.g. `iPhone16,2`).
`orientation`	string	Screen orientation (e.g. `portrait`).
`carrier`	string	Mobile carrier name.
`radio`	string	Connection type (e.g. `Wifi`).
`lib_version`	string	SDK library version.
`wifi`	boolean	Whether the device is on Wi-Fi.
`app_version`	string \| null	App version.
`tapcart_build`	string \| null	Tapcart build version.
`external_build`	string \| null	External build version.
`tapcart_commit_hash`	string \| null	Tapcart commit hash.
`consumer_type`	string	Consumer type (e.g. `Returning`).
`device_id`	string	Unique device identifier.
`prev_push_enabled`	boolean	Whether push was previously enabled.
`push_enabled`	boolean	Whether push is currently enabled.

Additional App Properties

Field	Type	Description
`currency_code`	string	Store currency code (e.g. `USD`).
`external_build`	string	External build version.
`tapcart_commit_hash`	string \| null	Tapcart commit hash.
`environment`	string	Environment name (e.g. `release`).

Additional Session Properties

Field	Type	Description
`session_type`	string	Session type (e.g. `Returning`).
`session_start_time`	number	Session start time in epoch milliseconds.
`notification_id`	string \| null	Notification identifier that triggered the session.
`notification_type`	string \| null	Type of notification.
`utm_source`	string \| null	UTM source parameter.
`utm_medium`	string \| null	UTM medium parameter.
`utm_campaign`	string \| null	UTM campaign parameter.
`utm_content`	string \| null	UTM content parameter.
`utm_term`	string \| null	UTM term parameter.
`external_notification_id`	string \| null	External notification identifier.
`segment_id`	string \| null	Segment identifier.

📝 Note: The notification_id field in session_properties may also appear on standard-format events when the session was triggered by a notification (e.g. InboxItemViewed).

Example Payload (Extended Format)

{
  "event_type": "CustomBlockViewed",
  "metadata": {
    "schema_id": "Event_CustomBlockViewed_10_1_0"
  },
  "device_properties": {
    "ip": "USER'S IP",
    "os": "iOS",
    "model": "iPhone16,2",
    "orientation": "portrait",
    "carrier": "--",
    "radio": "Wifi",
    "manufacturer": "Apple",
    "lib_version": "10.1.6",
    "country": "US",
    "locale": "en",
    "wifi": true,
    "app_version": null,
    "tapcart_build": null,
    "external_build": null,
    "os_version": "26.3",
    "tapcart_commit_hash": null,
    "consumer_type": "Returning",
    "device_id": "UNIQUE DEVICE ID",
    "prev_push_enabled": false,
    "push_enabled": false
  },
  "shopify_properties": {
    "shopify_user_id": null,
    "logged_in": false
  },
  "session_properties": {
    "session_id": "UNIQUE SESSION ID",
    "source": "direct",
    "session_type": "Returning",
    "session_start_time": 1776122472243,
    "notification_id": null,
    "notification_type": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "external_notification_id": null,
    "segment_id": null
  },
  "app_properties": {
    "app_id": "UNIQUE MERCHANT ID",
    "currency_code": "USD",
    "app_version": "6.3",
    "tapcart_build": "12.34.1",
    "external_build": "12.34.1",
    "os_version": "26.3",
    "tapcart_commit_hash": "9d5fc37",
    "environment": "release",
    "active_feature_experiments": "[...]"
  },
  "event_properties": {
    "event_id": "UNIQUE EVENT ID",
    "custom_block_id": "BLOCK ID",
    "custom_block_source_url": "https://tapcart.studio/...",
    "custom_block_index": 0,
    "custom_block_location": "phoenix_page",
    "static_position": null
  },
  "event_id": "UNIQUE EVENT ID",
  "device_id": "UNIQUE DEVICE ID",
  "app_id": "UNIQUE MERCHANT ID",
  "timestamp": 1776125036014,
  "timestamp_iso": "2026-04-13T17:03:56.014-07:00"
}

Event Properties by Type

AppOpened

Field	Type	Description
(empty object)		No additional properties.

AppInstalled

Field	Type	Description
`event_id`	string	Unique event identifier.

ProductViewed

Field	Type	Description
`product_id`	string	Shopify product ID.
`product_title`	string	Product name.
`product_price`	string	Product price.
`multi_currency_code`	string	Currency code (e.g. `USD`).
`product_tags_list`	string[]	Array of product tags.

CollectionViewed

Field	Type	Description
`collection_id`	string	Shopify collection ID.
`collection_title`	string	Collection title.

CartUpdated

Field	Type	Description
`update_type`	string	Type of update (e.g. `product_removed`).
`cart_id`	string	Cart identifier.
`quantity_updated`	number \| null	Quantity change.
`variant_id`	string	Shopify variant ID.
`cart_total_price`	string	Total cart price.
`multi_currency_code`	string	Currency code.
`cart_total_items`	number	Total items in cart.
`product_id`	string	Shopify product ID.
`product_title`	string	Product name.
`product_tags_list`	string[]	Array of product tags.

CheckoutCreated

Field	Type	Description
`checkout_amount`	number	Checkout total amount.
`currency_code`	string	Currency code.
`checkout_subtotal`	number \| null	Checkout subtotal.
`checkout_total_items`	number	Total items in checkout.
`checkout_items_list`	string[]	List of item names.
`total_discount_amount`	number	Total discount applied.

PurchaseCompleted

Field	Type	Description
`cart_id`	string	Cart identifier.
`checkout_id`	string	Checkout identifier.
`checkout_source_type`	string	Source type (e.g. `cart`).
`total_price`	number	Total purchase price.
`purchase_total_price`	number	Total purchase price.
`currency_code`	string	Currency code.
`product_ids`	string[]	Array of Shopify product IDs.
`total_discount_amount`	number	Total discount applied.

PageView

Field	Type	Description
`page_id`	string	Page identifier.
`page_gid`	string \| null	Page global identifier.
`page_type`	string	Page type (e.g. `wishlist-detail`).
`page_url`	string	Full page URL.

WishlistUpdated

Field	Type	Description
`wishlist_update_type`	string	Type of update (e.g. `wishlist_item_added`).

WishlistItemAdded

Field	Type	Description
`product_id`	string	Shopify product ID.
`product_title`	string	Product name.
`product_price`	number	Product price.
`multi_currency_code`	string	Currency code.

AccountCreated

Field	Type	Description
`account_shopify_user_id`	string	Shopify user ID for the new account.

InboxItemViewed

Field	Type	Description
`notification_id`	string	Notification identifier.
`notification_title`	string	Notification title.
`notification_message`	string	Notification body text.
`notification_image`	string	Notification image URL.

CustomBlockViewed

Field	Type	Description
`event_id`	string	Unique event identifier.
`custom_block_id`	string	Custom block identifier.
`custom_block_source_url`	string	Source URL of the custom block.
`custom_block_index`	number	Position index of the block.
`custom_block_location`	string	Location type (e.g. `phoenix_page`).
`static_position`	string \| null	Static position value.

Known Event Types

Event Type	Format	Description
`AppOpened`	Standard	User opened the app.
`AppInstalled`	Standard	User installed the app.
`ProductViewed`	Standard	User viewed a product.
`CollectionViewed`	Standard	User viewed a collection.
`CartUpdated`	Standard	User updated their cart.
`CheckoutCreated`	Standard	User initiated checkout.
`PurchaseCompleted`	Standard	User completed a purchase.
`PageView`	Standard	User viewed a page.
`WishlistUpdated`	Standard	User updated their wishlist.
`WishlistItemAdded`	Standard	User added an item to their wishlist.
`AccountCreated`	Standard	User created an account.
`InboxItemViewed`	Standard	User viewed an inbox notification.
`CustomBlockViewed`	Extended	User viewed a custom block.

📘 Important Note

Every event received from the webhook will represent new data. The Insight Data Streaming webhook does not provide any historical data previous to when the webhook was setup.