API Reference

Connecting to Insights Data Stream

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>

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, the merchant will need to reach out to the Tapcart team via email. The Tapcart Team will take the URL and then subscribe the merchant to a dedicated topic to receive POST requests from Tapcart’s Data Sync Webhook.

Please email the URL to: [email protected]

How will I know data has successfully been sent?

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.

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.