GetSocial Webhooks

GetSocial webhooks allow you to receive Smart Invites and Smart Links events in real time, which can be used for attribution.

Introduction

Webhooks are delivered as HTTP post requests where the request body contains the JSON encoded event. We expect your webhook endpoint to respond with a 200 OK status within 5 seconds. Any other situation is considered to be a failure.

When a failure is encountered, we stop sending requests and retry again after a short delay. This delay starts with 1 second and increases gradually up to 1 minute. At that point, we keep retrying every 1 minute. We might stop retrying permanently if your endpoint remains unavailable for an extended period of time (days, typically).

Security

Webhook requests made by GetSocial servers include a header, X-Getsocial-Signature.

You can (and should) use this header to verify the origin and integrity of the payload. The signature is the SHA256 hash of the payload, in lowercase hexits, using the Shared Secret in your GetSocial Dashboard as the key. See Sample Request and Validation below for an example.

If you are limiting the calls from external IP addresses to your backend, you have to whitelist the following IP addresses:

  • 54.156.214.206/32
  • 34.227.235.196/32

Event Details

App Install Event

This event is triggered when a user installs the app as a result of a Smart Link click.

Field Type Value
unique_id string A unique ID for this event. You can store this value to prevent replay attacks or duplicate events.
user_id string GetSocial user ID.
event string Name of the event. Set to app_install.
provider string Name of the invite provider the Smart Invites link was sent from. For Smart Invites, valid values are email, whatsapp, sms, facebook, facebookmessenger, twitter, kik, kakao, nativeshare, line, snapchat, telegram, viber, vk, hangouts, instagram, web. For Smart Links, this field is set to the channel of your link.
referrer object Only exists for Smart Invites links. An object with information about the user who created the link. It has 3 fields:

ID: GetSocial user ID.
IDFA: IDFA of the user, if any.
Identities: Custom identities associated with this user.
device object An object with information about the device the link was clicked from. It has the following properties:

Manufacturer: Manufacturer of the device.
Model: Model of the device.
Language: Device language.
OS: Operating system.
OSVersion: Operating system version.
Carrier: Mobile carrier name.
IDFA: ID for advertising.
IDFV: ID for vendor.
custom_data object Set of key/value pairs containing:
  • One of the below, depending on the product. These keys always start with the $ sign (see Referral Data Reference).
    • For Smart Invites, information about the link, like the provider (e.g. sms) and a unique ID for the link.
    • For Smart Links, information about the campaign and the link.
  • Referral data passed to the SDK during Smart Invites link creation. See “How to send Referral Data” guide for Android, iOS or Unity.
guaranteed_match boolean This flag indicates if GetSocial guarantees that referral data corresponds to the user. If we can retrieve extra meta information (e.g. from Google Play, Facebook or deep link), we guarantee the match and return true. If meta data is not available, we use fingerprinting to find the best match and return false.
reinstall boolean This flag indicates if the app was previously installed on this device. It is not 100% reliable as device identifiers are not always available.

App Open Event

This event is triggered when an existing user opens the app as a result of a Smart Link click. Learn how to receive Referral Data.

Field Type Value
unique_id string A unique ID for this event. You can store this value to prevent replay attacks or duplicate events.
user_id string GetSocial user ID.
event string Name of the event. Set to app_open.
provider string Name of the invite provider the Smart Invites link was sent from. For Smart Invites, valid values are email, whatsapp, sms, facebook, facebookmessenger, googleplus, twitter, kik, kakao, nativeshare, line, snapchat, telegram, viber, vk, hangouts, instagram, web. For Smart Links, this field is set to the channel of your link.
first_match boolean Flag indicating whether it is the first time the referral data is requested from the current device for current Smart Invite link.
referrer object Only exists for Smart Invites links. An object with information about the user who created the Smart Invites link. It has 3 fields:

ID: GetSocial user ID.
IDFA: IDFA of the user, if any.
Identities: Custom identities associated with this user.
custom_data object Set of key/value pairs containing:
  • One of the below, depending on the product. These keys always start with the $ sign (see Referral Data Reference.
    • For Smart Invites, information about the link, like the provider (e.g sms) and a unique ID for the link.
    • For Smart Links, information about the campaign and the link.
  • Referral data passed to the SDK during Smart Invites link creation. See “How to send Referral Data” guide for Android, iOS or Unity.
guaranteed_match boolean This flag indicates if GetSocial guarantees that referral data corresponds to the user. If we can retrieve extra meta information (e.g. from Google Play, Facebook or deep link), we guarantee the match and return true. If meta data is not available, we use fingerprinting to find the best match and return false.

Web Signup Event

This event is triggered when a signs up via the Web SDK as a result of a Smart Link click.

Field Type Value
unique_id string A unique ID for this event. You can store this value to prevent replay attacks or duplicate events.
user_id string GetSocial user ID.
event string Name of the event. Set to web_signup.
provider string Name of the invite provider the Smart Invites link was sent from. For Smart Invites, valid values are email, whatsapp, sms, facebook, facebookmessenger, twitter, kik, kakao, nativeshare, line, snapchat, telegram, viber, vk, hangouts, instagram, web. For Smart Links, this field is set to the channel of your link.
referrer object Only exists for Smart Invites links. An object with information about the user who created the link. It has 3 fields:

ID: GetSocial user ID.
IDFA: IDFA of the user, if any.
Identities: Custom identities associated with this user.
custom_data object Set of key/value pairs containing:
  • One of the below, depending on the product. These keys always start with the $ sign (see Referral Data Reference).
    • For Smart Invites, information about the link, like the provider (e.g. sms) and a unique ID for the link.
    • For Smart Links, information about the campaign and the link.
  • Referral data passed to the SDK during Smart Invites link creation. See “How to send Referral Data” guide for Android, iOS or Unity.

Web Open Event

This event is triggered when an existing user authenticates with the Web SDK a result of a Smart Link click. Learn how to receive Referral Data.

Field Type Value
unique_id string A unique ID for this event. You can store this value to prevent replay attacks or duplicate events.
user_id string GetSocial user ID.
event string Name of the event. Set to web_open.
provider string Name of the invite provider the Smart Invites link was sent from. For Smart Invites, valid values are email, whatsapp, sms, facebook, facebookmessenger, googleplus, twitter, kik, kakao, nativeshare, line, snapchat, telegram, viber, vk, hangouts, instagram, web. For Smart Links, this field is set to the channel of your link.
referrer object Only exists for Smart Invites links. An object with information about the user who created the Smart Invites link. It has 3 fields:

ID: GetSocial user ID.
IDFA: IDFA of the user, if any.
Identities: Custom identities associated with this user.
custom_data object Set of key/value pairs containing:
  • One of the below, depending on the product. These keys always start with the $ sign (see Referral Data Reference.
    • For Smart Invites, information about the link, like the provider (e.g sms) and a unique ID for the link.
    • For Smart Links, information about the campaign and the link.
  • Referral data passed to the SDK during Smart Invites link creation. See “How to send Referral Data” guide for Android, iOS or Unity.

Register Webhook URL

To register a webhook URL:

  1. Login to your account on the GetSocial Dashboard.
  2. Go to Data Export section → Webhooks tab.

    Webhooks Setup - GetSocial Dashboard

  3. Enter your Webhook URL and click the save icon in the lower right corner.

  4. (Optional) For testing purposes you can use hookbin.com to create a temporary URL which you can use as a webhook.
  5. (Optional) You can use Shared Secret to validate webhook requests. Example is below.

Sample Request and Validation

Consider the following app_install event.

Request HTTP headers:

1
2
3
X-Getsocial-Signature: fa17bd76469cf5daf46061e3530188bc4d1f3a7c02d5706e528653e1782867f5
X-Request-Id: d9696448-b94b-4131-ae52-759ec33a17ad
User-Agent: GetSocial_Webhooks/1.0

Request Body:

1
{"unique_id":"4feb25ef-64f7-4bd8-bc13-f3dd6657bb32","user_id":"86954330754758633","event":"app_install","provider":"facebook","device":{"model":"Android SDK built for x86","manufacturer":"unknown","language":"en-US","os":"Android","os_version":"6.0","carrier":"Android","idfv":"","idfa":"cce677ed-92c2-48aa-9b74-96a0eb0b12bb"},"referrer":{"id":"84628512169208288","idfa":"cf9188fe-3b5d-4ba1-925d-78637ae41a6b","identities":{"custom":"fuv"}},"custom_data":{"$id":"d9RwHx4JqA","$provider":"facebook","$referrer_user_guid":"84628512169208288","$referrer_user_idfa":"cf9188fe-3b5d-4ba1-925d-78637ae41a6b"},"guaranteed_match":false,"reinstall":false}

Note that the request body is sent as a single line. For demonstration purposes, see a formatted version below:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "unique_id": "4feb25ef-64f7-4bd8-bc13-f3dd6657bb32",
  "user_id": "86954330754758633",
  "event": "app_install",
  "provider": "facebook",
  "device": {
    "model": "Android SDK built for x86",
    "manufacturer": "unknown",
    "language": "en-US",
    "os": "Android",
    "os_version": "6.0",
    "carrier": "Android",
    "idfv": "",
    "idfa": "cce677ed-92c2-48aa-9b74-96a0eb0b12bb"
  },
  "referrer": {
    "id": "84628512169208288",
    "idfa": "cf9188fe-3b5d-4ba1-925d-78637ae41a6b",
    "identities": {
      "custom": "fuv"
    }
  },
  "custom_data": {
    "$id": "d9RwHx4JqA",
    "$provider": "facebook",
    "$referrer_user_guid": "84628512169208288",
    "$referrer_user_idfa": "cf9188fe-3b5d-4ba1-925d-78637ae41a6b"
  },
  "guaranteed_match": false,
  "reinstall": false
}

We can verify and parse this with the following code (use the language selection on the sidebar). If you are having trouble validating or parsing the request, please feel free to contact us. We would be happy to help.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
<?php
// Read the POST body
$body = file_get_contents('php://input');

// Verify request
$hash = hash_hmac('sha256', $body, "Shared secret from the Developer Dashboard");

if (hash_equals($hash, $_SERVER['HTTP_X_GETSOCIAL_SIGNATURE']) === false) {
  echo "Invalid signature";
  return;
}

// Parse the JSON
$parsed = json_decode($body, true);

// Get attribution data
echo $parsed["event"]." event received for user ".$parsed["user_id"];

if (isset($parsed["referrer"]["id"])) {
 echo ", who was referred by ".$parsed["referrer"]["id"];
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Node.js example with Express (https://expressjs.com/)
const express = require('express');
const crypto = require("crypto");
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.raw({
  inflate: true,
  limit: '512kb',
  type: 'application/json'
}));

sharedSecret = "shared secret from dashboard";

app.post('/', function (req, res) {
  // Validate signature
  signature = crypto.createHmac("sha256", sharedSecret).update(req.body).digest("hex");
  if (signature != req.headers["x-getsocial-signature"]) {
    res.end("Invalid webhook");
    return;
  }

  // Parse body
  var body = JSON.parse(req.body);

  // Get attribution data
  resp = body.event + " event received for user " + body.user_id;
  if (typeof body.referrer !== "undefined" && typeof body.referrer.id !== "undefined") {
    resp += ", who was referred by " + body.referrer.id;
  }

  res.end(resp);
})

app.listen(3000, function () {
  console.log('Webhook server listening on port 3000!')
})

Give us your feedback! Was this article helpful?

😀 🙁