This webhook adapter lets you track events sent via a GET
or POST
request containing an Iglu-compatible event payload.
You can use this adapter with vendors who allow you define your own event types for “postback”. An example of a vendor who supports this is AD-X Tracking.
Setup
Integrating Iglu-compatible webhooks into Snowplow is a two-stage process:
- Configure your third-party system to send Iglu-compatible events to Snowplow
- (Optional) Setup the appropriate JSON Schema, JSON Paths file and Redshift table definition for each Iglu-compatible event you are sending through
Your webhook
The Iglu webhook adapter supports events send in as GET
and POST
requests.
Path
We use a special path to tell Snowplow that these events should be parsed as Iglu self-describing JSON events, thus:
http://<collector host>/com.snowplowanalytics.iglu/v1?schema=<iglu schema uri>&...
Code language: HTML, XML (xml)
Required fields
You can send in whatever name-value pairs on the querystring that make sense for your event, but you must also include a schema
parameter, which is set to a valid Iglu self-describing schema URI, such as:
iglu:com.acme.postbacks/install_error/jsonschema/1-0-0
Optional fields
If you want to specify which app these events belong to, add an aid
parameter as taken from the Snowplow Tracker Protocol:
...&aid=<company code>&...
Code language: HTML, XML (xml)
You can also manually override the event’s platform
parameter like so:
...&p=<platform code>&...
Code language: HTML, XML (xml)
Supported platform codes can again be found in the Snowplow Tracker Protocol; if not set, then the value for platform
will default to srv
for a server-side application.
Example GET
request
Here is an example of an Iglu-compatible event sent as a GET
request, broken out onto multiple lines to make it easier to read:
http://snplow.acme.com/com.snowplowanalytics.iglu/v1
?schema=iglu%3Acom.acme%2Fcampaign%2Fjsonschema%2F1-0-0
&aid=mobile-attribution&p=mob
&user=6353af9b-e288-4cf3-9f1c-b377a9c84dac&name=download&publisher_name=Organic&source=&tracking_id=&ad_unit=
Code language: JavaScript (javascript)
This will be converted by the Iglu webhook adapter into a self-describing JSON looking like this:
{
"schema":"iglu:com.acme/campaign/jsonschema/1-0-0",
"data": {
"name":"download",
"source":null,
"ad_unit":null,
"tracking_id":null,
"publisher_name":"Organic",
"user":"6353af9b-e288-4cf3-9f1c-b377a9c84dac"
}
}
Code language: JSON / JSON with Comments (json)
The Snowplow enriched event containing this JSON will include app_id
set to “mobile-attribution” and platform
set to “mob”.
Example POST
request
POST requests can be compiled in two different ways for the Iglu webhook:
- As a full SelfDescribing JSON in the body
- With a
?schema=<iglu schema uri>
in the querystring and a data JSON in the body
NOTE: For the event to be accepted the Content-Type
must be either:
application/json
application/json; charset=utf-8
To send the first type:
http://snplow.acme.com/com.snowplowanalytics.iglu/v1 -d '{
"schema":"iglu:com.acme/campaign/jsonschema/1-0-0",
"data": {
"name":"download",
"source":null,
"ad_unit":null,
"tracking_id":null,
"publisher_name":"Organic",
"user":"6353af9b-e288-4cf3-9f1c-b377a9c84dac"
}
}'
Code language: PHP (php)
To send the second type:
http://snplow.acme.com/com.snowplowanalytics.iglu/v1?schema=iglu%3Acom.acme%2Fcampaign%2Fjsonschema%2F1-0-0 -d '{
"name":"download",
"source":null,
"ad_unit":null,
"tracking_id":null,
"publisher_name":"Organic",
"user":"6353af9b-e288-4cf3-9f1c-b377a9c84dac"
}'
Code language: PHP (php)
As with the GET
request above you can also attach extra information into the querystring to help describe your event. The following parameters can be added:
aid=
: The application IDp=
: The platformnuid=
: The network user IDeid=
: A custom event IDttm=
: The true timestampurl=
: The page URLcv=
: The context vendor (deprecated)