In order to connect to your Insights Data Streaming, you will need to ensure the following steps are followed:

  1. Generate an HTTPS URL that can receive POST requests
  2. Send that URL to the Tapcart Team
  3. Tapcart Team will then begin to send data directly to the HTTPS URL via webhook
  4. Ensure events are streaming via the webhook

Tapcart Webhooks Overview

Webhooks are a way for you to stay in sync with the data that Tapcart provides. These webhooks can notify you when user events flow through the mobile apps and you can process that data from JSON payloads from the response.

A webhook subscription allows your app to subscribe to Tapcart’s event data , listen for when an event occurs, and then receive a JSON payload on the event creation.

  1. The Tapcart merchant specifies an HTTPS endpoint hosted by the merchant’s REST server to receive events for the topic
  2. The Tapcart Merchant will be subscribed to Tapcart’s Insights Data Sync Topic and listen for events sent from Tapcart
  3. An event in the mobile app occurs
  4. The event is published to the Merchant’s Insights Data Stream Subscription
  5. Tapcart will then send a POST request with an event payload in JSON format in the body to the registered subscription endpoint

Setup

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>

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, [email protected], and provide your endpoint URL. The Tapcart Team will take the endpoint URL and then subscribe you to a dedicated topic to receive POST requests.

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

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 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.

Auth Headers

Accept	application/json
Accept-Encoding	gzip, deflate, br
App_id	Ao6SaGAvub
Authorization	Bearer eyJhbG
Content-Length	1576
Content-Type	application/json
Event_id	CDC9EE12-C5BA-4568-82CD-F16B555E2B7A
Event_type	AppOpened
From	[email protected]
Host	f7ae-172-91-112-226.ngrok-free.app
Schema_id	Event_AppOpened_10_0_0
Timestamp	1698352913416
User-Agent	APIs-Google; (+https://developers.google.com/webmasters/APIs-Google.html)
X-Forwarded-For	64.233.172.67
X-Forwarded-Host	f7ae-172-91-112-226.ngrok-free.app
X-Forwarded-Proto	https
X-Goog-Pubsub-Message-Id	9483226130714580
X-Goog-Pubsub-Publish-Time	2023-10-26T20:42:24.615Z
X-Goog-Pubsub-Subscription-Name	projects/insights-data-sync/subscriptions/data-sync-Ao6SxGAvux-14ce2bec2d9

Payload Example:

Upon receiving a successful 200 POST request from the Insights Data Stream 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 Tapcart receives any new events. So, as Tapcart collects any new event activity, those same events will be sent via the webhook.

An example of an event payload can be seen below:

{  
   "event_type":"AppOpened",  
   "metadata":{  
      "schema_id":"Event_AppOpened_5_0_0"  
   },  
   "device_properties":{  
      "ip":"USER’S IP",  
      "os":"iOS",  
      "model":"arm64",  
      "orientation":"portrait",  
      "carrier":"",  
      "radio":"Wifi",  
      "manufacturer":"Apple",  
      "lib_version":"4.1.5",  
      "country":"US",  
      "locale":"en",  
      "wifi":true,  
      "app_version":null,  
      "tapcart_build":null,  
      "external_build":null,  
      "os_version":"15.5",  
      "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":1692140759000,  
      "notification_id":null,  
      "notification_type":null,  
      "utm_source":null,  
      "utm_medium":null,  
      "utm_campaign":null,  
      "utm_content":null,  
      "utm_term":null  
   },  
   "app_properties":{  
      "app_id":"UNIQUE MERCHANT ID",  
      "currency_code":"USD",  
      "app_version":"1.0.0",  
      "tapcart_build":"10.4.0",  
      "external_build":"10.4.0",  
      "os_version":"15.5",  
      "tapcart_commit_hash":null,  
      "environment":"debug"  
   },  
   "event_properties":{  
      "source":null,  
      "event_id":"UNIQUE EVENT ID",  
      "app_open_source":"direct",  
      "notification_id":null,  
      "notification_type":null  
   },  
   "event_id":UNIQUE EVENT ID",  
   "session_id":"UNIQUE SESSION ID",  
   "device_id":"UNIQUE DEVICE ID",  
   "app_id":"UNIQUE MERCHANT ID",  
   "timestamp":1663008666001,  
   "timestamp_iso":"2023-08-15T11:51:06.000-07:00"  
}

The above event is an AppOpened event performed by an individual user. The payload includes unique DeviceProperties, SessionProperties, EventProperties, ShopifyProperties, and AppProperties.

📘

Important Notes:

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.