Iglu Webhook

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:

1. Configure your third-party system to send Iglu-compatible events to Snowplow
2. (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 ID
• p= : The platform
• nuid= : The network user ID
• eid= : A custom event ID
• ttm= : The true timestamp
• url= : The page URL
• cv= : The context vendor (deprecated)