In order to connect to your Insights Data Streaming, you will need to ensure the following steps are followed:
- Generate an HTTPS URL that can receive POST requests
- Send that URL to the Tapcart Team
- Tapcart Team will then begin to send data directly to the HTTPS URL via webhook
- 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.
- The Tapcart merchant specifies an HTTPS endpoint hosted by the merchant’s REST server to receive events for the topic
- The Tapcart Merchant will be subscribed to Tapcart’s Insights Data Sync Topic and listen for events sent from Tapcart
- An event in the mobile app occurs
- The event is published to the Merchant’s Insights Data Stream Subscription
- 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.