Collecting data with Trackers and Webhooks

  1. Home
  2. Docs
  3. Collecting data with Trackers and Webhooks
  4. Webhooks – collecting data from third parties
  5. Iglu Webhook

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

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

You can also manually override the event’s platform parameter like so:

...&p=<platform code>&...

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=

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" } }

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" } }'

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" }'

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)