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” events or custom Webhook events.

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. Setup the appropriate JSON Schema 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:

http://{{COLLECTOR_URL}}/com.snowplowanalytics.iglu/v1?schema=<iglu schema uri>&...
Code language: plaintext (plaintext)

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.

iglu:com.snowplowanalytics.snowplow/social_interaction/jsonschema/1-0-0
Code language: plaintext (plaintext)

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, for a Social Interacton event, broken out onto multiple lines to make it easier to read:

http://{{COLLECTOR_URL}}/com.snowplowanalytics.iglu/v1?schema=iglu%3Acom.snowplowanalytics.snowplow%2Fsocial_interaction%2Fjsonschema%2F1-0-0
  &aid=mobile-attribution
  &p=mob
  &network=twitter
  &action=retweet
Code language: Bash (bash)

This will be converted by the Iglu webhook adapter into a self-describing JSON looking like this:

{
  "schema":"iglu:com.snowplowanalytics.snowplow/social_interaction/jsonschema/1-0-0",
  "data": {
    "network": "twitter",
    "action": "retweet"
  }
}
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 requests

POST requests can be compiled in three different ways for the Iglu webhook:

• As a full Self Describing JSON in the body
• With a ?schema=<iglu schema uri> in the querystring and JSON in the body
• As a x-www-form-urlencoded payload

NOTE: For the event to be accepted the Content-Type must be either:

• application/json
• application/json; charset=utf-8
• application/x-www-form-urlencoded

To send as a full Self Describing JSON in the body and a Content-Type of application/json:

curl --request POST \
   --url http://{{COLLECTOR_URL}}/com.snowplowanalytics.iglu/v1 \
   --header 'Content-Type: application/json' \
   --data '{
   "schema":"iglu:com.snowplowanalytics.snowplow/social_interaction/jsonschema/1-0-0",
   "data": {
         "network": "twitter",
         "action": "retweet"
     }
 }'
Code language: Bash (bash)

To send with a ?schema=<iglu schema uri> in the querystring and a data JSON in the body and Content-Type of application/json:

curl --request POST \
   --url 'http://{{COLLECTOR_URL}}/com.snowplowanalytics.iglu/v1?schema=iglu%3Acom.snowplowanalytics.snowplow%2Fsocial_interaction%2Fjsonschema%2F1-0-0' \
   --header 'Content-Type: application/json' \
   --data '{
   "network": "twitter",
   "action": "retweet"
 }'
Code language: Bash (bash)

To send as a x-www-form-urlencoded payload:

curl --request POST \
   --url 'http://{{COLLECTOR_URL}}/com.snowplowanalytics.iglu/v1?schema=iglu%3Acom.snowplowanalytics.snowplow%2Fsocial_interaction%2Fjsonschema%2F1-0-0' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data 'network=twitter&action=retweet'
Code language: Bash (bash)

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)