GetSocial Webhooks v2

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

Versioning

To make sure that the Webhook format can evolve over time we added a version field that you can use to identify and parse accordingly.

When we introduce new versions, we freeze existing integrations to the current previous version to make sure we don’t break your code.

If you are interested in upgrading to newer version please contact us.

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

Webhooks also include unique_id field that contains a unique ID for each single event we send.

You can store this value to prevent replay attacks or duplicate events.

Webhook Details

This documentation is valid for v2 (current version) of the webhooks.

Are you looking for documentation of previous versions?

Make sure to check the webhook documentation for deprecated versions?

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.
version number The version of the Webhook. Current version is 2
user object User that installed the app.
user.id string GetSocial ID of the user.
user.idfa string ID for Advertisers of the user, if available.
user.identities map Map of identities of the user.
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, 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.
referrer.id string GetSocial ID of the user.
referrer.idfa string ID for Advertiser of the user, if available.
referrer.identities map Map of identities of the user.
device object Device the link was clicked on.
device.manufacturer string Manufacturer of the device.
device.model string Manufacturer of the device.
device.language string Device language.
device.os string Operating system.
device.os_version string Operating system version.
device.carrier string Mobile carrier name.
device.idfv string ID for vendor.
device.idfa string ID for Advertisers.
custom_data map 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.
suspicious boolean This flag indicates if GetSocial detected that this might be an install that is suspicious of fraud. Some of the reasons include
  • Sender and receiver have the same IP
  • Receiver has reset the IDFA between installs
  • We detected multiple installs from the same IP for the same referrer

Sample webhook

 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
37
38
39
40
41
42
43
44
45
{
  "timestamp": "2020-07-09T11:45:35Z",
  "unique_id": "3a10e790-cb51-4169-a182-e257599295b5",
  "event": "app_install",
  "version": 2,
  "user": {
    "id": "465845974247550000",
    "idfa": "ab77128f-dade-42cb-b756-000000000000",
    "identities": {
      "internal_id": "11111"
    }
  },
  "referrer": {
    "id": "465838842323800000",
    "idfa": "348dc5a8-fe87-4248-8256-000000000000",
    "identities": {
      "internal_id": "22222"
    },
  },
  "custom_data": {
    "$channel": "email",
    "$first_match": "true",
    "$first_match_link": "false",
    "$guaranteed_match": "true",
    "$referrer_user_guid": "465838842323800000",
    "$referrer_user_idfa": "348dc5a8-fe87-4248-8256-000000000000",
    "$reinstall": "false",
    "$suspicious": "true",
    "$token": "yzONV3ZcEi"
  },
  "device": {
    "model": "HTC 2Q4R100",
    "manufacturer": "HTC",
    "language": "zh-TW",
    "os": "Android",
    "os_version": "7.1.2",
    "carrier": "csl.",
    "idfv": "",
    "idfa": "ab77128f-dade-42cb-b756-000000000000"
  },
  "provider": "email",
  "guaranteed_match": true,
  "reinstall": false,
  "suspicious": true
}

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 on Android, iOS or Unity.

Field Type Value
unique_id string A unique ID for this event. You can store this value to prevent replay attacks or duplicate events.
version number The version of the Webhook. Current version is 2.
user object User that opened the app from a GetSocial Smart Invite or Smart Link.
user.id string GetSocial ID of the user.
user.idfa string ID for Advertisers of the user, if available.
user.identities map Map of identities of the user.
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, telegram, viber, vk, hangouts, instagram, web. For Smart Links, this field is set to the channel of your link.
device object Device the link was clicked on.
device.manufacturer string Manufacturer of the device.
device.model string Manufacturer of the device.
device.language string Device language.
device.os string Operating system.
device.os_version string Operating system version.
device.carrier string Mobile carrier name.
device.idfv string ID for vendor.
device.idfa string ID for Advertisers.
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 link.
referrer.id string GetSocial ID of the user.
referrer.idfa string ID for Advertiser of the user, if available.
referrer.identities map Map of identities of the user.
custom_data map 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.

Sample webhook

 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
37
38
39
40
41
42
43
{
  "timestamp": "2020-07-09T11:13:09Z",
  "unique_id": "d01cad33-b6d2-4e43-ae21-43a6905e66b6",
  "event": "app_open",
  "version": 2,
  "user": {
    "id": "465837050423230000",
    "idfa": "ab77128f-dade-42cb-b756-000000000000",
    "identities": {
      "internal_id": "11111"
    },
  },
  "referrer": {
    "id": "465834005115170000",
    "idfa": "348dc5a8-fe87-4248-8256-000000000000",
    "identities": {
      "internal_id": "22222"
    },
  },
  "custom_data": {
    "$channel": "email",
    "$first_match": "false",
    "$first_match_link": "true",
    "$guaranteed_match": "true",
    "$referrer_user_guid": "465834005115170000",
    "$referrer_user_idfa": "348dc5a8-fe87-4248-8256-000000000000",
    "$reinstall": "false",
    "$suspicious": "true",
    "$token": "OTeiJd2VFf"
  },
  "device": {
    "model": "HTC 2Q4R100",
    "manufacturer": "HTC",
    "language": "zh-TW",
    "os": "Android",
    "os_version": "7.1.2",
    "carrier": "csl.",
    "idfv": "",
    "idfa": "ab77128f-dade-42cb-b756-000000000000"
  },
  "provider": "email",
  "first_match": true
}

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.
version number The version of the Webhook. Current version is 2.
user object User that signed up from a GetSocial Smart Invite or Smart Link.
user.id string GetSocial ID of the user.
user.identities map Map of identities of the user.
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, 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.
referrer.id string GetSocial ID of the user.
referrer.identities map Map of identities of the user.
custom_data map 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.

Sample webhook

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "timestamp": "2020-07-09T11:45:35Z",
  "unique_id": "3a10e790-cb51-4169-a182-e257599295b5",
  "event": "web_signup",
  "version": 2,
  "user": {
    "id": "465845974247550000",
    "identities": {
      "internal_id": "11111"
    }
  },
  "referrer": {
    "id": "465838842323800000",
    "identities": {
      "internal_id": "22222"
    }
  },
  "custom_data": {
    "$channel": "email",
    "$token": "yzONV3ZcEi"
  },
  "provider": "email"
}

Web Open Event

This event is triggered when an existing user authenticates with the Web SDK 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.
version number The version of the Webhook. Current version is 2.
user object User that opened the website from a GetSocial Smart Invite or Smart Link.
user.id string GetSocial ID of the user.
user.identities map Map of identities of the user.
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, 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.
referrer.id string GetSocial ID of the user.
referrer.identities map Map of identities of the user.
custom_data map 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.

Sample webhook

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "timestamp": "2020-07-09T11:13:09Z",
  "unique_id": "d01cad33-b6d2-4e43-ae21-43a6905e66b6",
  "event": "web_open",
  "version": 2,
  "user": {
    "id": "465837050423230000",
    "identities": {
      "internal_id": "11111"
    }
  },
  "referrer": {
    "id": "465834005115170000",
    "identities": {
      "internal_id": "22222"
    }
  },
  "custom_data": {
    "$channel": "email",
    "$token": "OTeiJd2VFf"
  },
  "provider": "email"
}

Smart Flows

Triggered as an action from Smart Flows.

Field Type Value
unique_id string A unique ID for this event. You can store this value to prevent replay attacks or duplicate events.
version number The version of the Webhook. Current version is 2
user object User that triggered the SmartFlow
user.id string GetSocial ID of the user.
user.display_name string Display Name of the user.
user.avatar string Avatar of the user.
user.identities map Map of identities of the user.
user.public_properties map Map of public properties of the user.
user.private_properties map Map of private properties of the user.
event string Name of the event. Set to the name of the event that triggered the Smart Flow.
referrer object Referrer of the user that triggered the SmartFlow
referrer.id string GetSocial ID of the user.
referrer.display_name string Display Name of the user.
referrer.avatar string Avatar of the user.
referrer.identities map Map of identities of the user.
referrer.public_properties map Map of public properties of the user.
referrer.private_properties map Map of private properties of the user.
custom_data map Set of key/value pairs defined in the Smart Flow action

Sample webhook

 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
37
{
  "unique_id": "4feb25ef-64f7-4bd8-bc13-f3dd6657bb32",
  "version": 2,
  "user": {
    "id": "134781878402181117",
    "display_name": "John",
    "avatar": "https://www.url.to/john_avatar",
    "identities": {
      "internal_id": "11111"
    },
    "public_properties": {
      "key": "value"
    },
    "private_properties": {
      "key": "value"
    }
  },
  "event": "x:subscription",
  "referrer": {
    "id": "134781878402130495",
    "display_name": "Karen",
    "avatar": "https://www.url.to/karen_avatar",
    "identities": {
      "internal_id": "22222"
    },
    "public_properties": {
      "key": "value"
    },
    "private_properties": {
      "key": "value"
    }
  },
  "custom_data": {
    "should_reward_referrer": "true",
    "reward": "10"
  },
}

Activities Create / Update

This event is triggered when a user creates or updates an activity, either posts or comments.

Field Type Value
unique_id string Unique ID for this event. You can store this value to prevent replay attacks or duplicate events.
version number Version of the Webhook. Current version is 2
event string Name of the event, either activity_created or activity_updated.
activity object Activity that was created or updated.
activity.id string GetSocial ID of the activity
activity.type string Either post or comment. If comment then activity.parent will contain information about the parent activity
activity.content object Content of the activity.
activity.content.language string Language of the content of the activity. (full list)
activity.content.text string Raw version of the text of the activity. Mentions will be shown as @1234567890
activity.content.enriched_text string Enriched version of the text of the activity. Mentions will be shown as @DisplayNameOfUserId1234567890
activity.content.attachments array Array of attachments (images or videos) of the activity
activity.author object Author of the activity.
activity.author.id string GetSocial ID of the user.
activity.author.display_name string Display Name of the user.
activity.author.avatar string Avatar of the user.
activity.author.identities map Map of identities of the user.
activity.author.public_properties map Map of public properties of the user.
activity.author.private_properties map Map of private properties of the user.
activity.target object Target of the activity.
activity.target.id string ID of the target.
activity.target.type string Type of target. Can be either topic, group or user.
activity.parent object Basic details from the parent activity. Only available if activity.type is comment.
activity.parent.id string GetSocial ID of the parent activity
activity.parent.author object Author of the parent activity.
activity.parent.author.id string GetSocial ID of the user.
activity.parent.author.display_name string Display Name of the user.
activity.parent.author.avatar string Avatar of the user.
activity.parent.author.identities map Map of identities of the user.
activity.parent.author.public_properties map Map of public properties of the user.
activity.parent.author.private_properties map Map of private properties of the user.
activity.created_at string Timestamp of the moment the activity was created
activity.version string Version of the activity useful for backwards compatibility

Sample webhook

 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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "timestamp": "2020-08-09T08:03:57Z",
  "unique_id": "4103e5f6-3604-486d-af3d-56a8d792100c",
  "event": "activity_created",
  "version": 2,
  "activity": {
    "id": "477024223928097147",
    "type": "comment",
    "content": {
      "language": "en",
      "text": "Hey @1234567890, This is a test",
      "enriched_text": "Hey @DisplayNameOfUserId1234567890, This is a test",
      "attachments": [
        {
          "image": "https://www.url.to/activity_image"
        },
        {
          "video": "https://www.url.to/activity_video"
        }
      ]
    },
    "author": {
      "id": "134781878402181117",
      "display_name": "John",
      "avatar": "https://www.url.to/john_avatar",
      "identities": {
        "internal_id": "11111"
      },
      "public_properties": {
        "key": "value"
      },
      "private_properties": {
        "key": "value"
      }
    },
    "target": {
      "id": "global",
      "type": "topic"
    },
    "parent": {
      "id": "477022930324562162",
      "author": {
        "id": "134781878402130495",
        "display_name": "Karen",
        "avatar": "https://www.url.to/karen_avatar",
        "identities": {
          "internal_id": "22222"
        },
        "public_properties": {
          "key": "value"
        },
        "private_properties": {
          "key": "value"
        }
      }
    },
    "created_at": "2020-08-09T08:03:57Z",
    "version": "1"
  }
}

Activities Reactions

This event is triggered when a user reacts or un-reacts on an activity, either posts or comments.

Field Type Value
unique_id string Unique ID for this event. You can store this value to prevent replay attacks or duplicate events.
version number Version of the Webhook. Current version is 2
event string Name of the event, either activity_reacted or activity_unreacted.
reaction string Type of Reaction of the user
user object User that reacted or un-reacted.
user.id string GetSocial ID of the user.
user.display_name string Display Name of the user.
user.avatar string Avatar of the user.
user.identities map Map of identities of the user.
user.public_properties map Map of public properties of the user.
user.private_properties map Map of private properties of the user.
activity object Activity that was reacted or unreacted.
activity.id string GetSocial ID of the activity
activity.type string Either post or comment. If comment then activity.parent will contain information about the parent activity
activity.content object Content of the activity.
activity.content.language string Language of the content of the activity. (full list)
activity.content.text string Raw version of the text of the activity. Mentions will be shown as @1234567890
activity.content.enriched_text string Enriched version of the text of the activity. Mentions will be shown as @DisplayNameOfUserId1234567890
activity.content.attachments array Array of attachments (images or videos) of the activity
activity.reactions map Map of reactions counters.
activity.author object Author of the activity.
activity.author.id string GetSocial ID of the user.
activity.author.display_name string Display Name of the user.
activity.author.avatar string Avatar of the user.
activity.author.identities map Map of identities of the user.
activity.author.public_properties map Map of public properties of the user.
activity.author.private_properties map Map of private properties of the user.
activity.target object Target of the activity.
activity.target.id string ID of the target.
activity.target.type string Type of target. Can be either topic, group or user.
activity.parent object Basic details from the parent activity. Only available if activity.type is comment.
activity.parent.id string GetSocial ID of the parent activity
activity.parent.author object Author of the parent activity.
activity.parent.author.id string GetSocial ID of the user.
activity.parent.author.display_name string Display Name of the user.
activity.parent.author.avatar string Avatar of the user.
activity.parent.author.identities map Map of identities of the user.
activity.parent.author.public_properties map Map of public properties of the user.
activity.parent.author.private_properties map Map of private properties of the user.
activity.created_at string Timestamp of the moment the activity was created
activity.version string Version of the activity useful for backwards compatibility

Sample webhook

 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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
{
  "timestamp": "2020-08-09T08:03:57Z",
  "unique_id": "4103e5f6-3604-486d-af3d-56a8d792100c",
  "event": "activity_reacted",
  "version": 2,
  "user": {
    "id": "134781878402181117",
    "display_name": "John",
    "avatar": "https://www.url.to/john_avatar",
    "identities": {
      "internal_id": "11111"
    },
    "public_properties": {
      "key": "value"
    },
    "private_properties": {
      "key": "value"
    }
  },
  "reaction": "like",
  "activity": {
    "id": "477024223928097147",
    "type": "comment",
    "content": {
      "language": "en",
      "text": "Hey @1234567890, This is a test",
      "enriched_text": "Hey @DisplayNameOfUserId1234567890, This is a test",
      "attachments": [
        {
          "image": "https://www.url.to/activity_image"
        },
        {
          "video": "https://www.url.to/activity_video"
        }
      ]
    },
    "reactions": {
      "like": 1,
      "wow": 3,
      "haha": 5
    },
    "author": {
      "id": "13478187840245324",
      "display_name": "Martin",
      "avatar": "https://www.url.to/martin_avatar",
      "identities": {
        "internal_id": "33333"
      },
      "public_properties": {
        "key": "value"
      },
      "private_properties": {
        "key": "value"
      }
    },
    "target": {
      "id": "global",
      "type": "topic"
    },
    "parent": {
      "id": "477022930324562162",
      "author": {
        "id": "134781878402130495",
        "display_name": "Karen",
        "avatar": "https://www.url.to/karen_avatar",
        "identities": {
          "internal_id": "12946"
        },
        "public_properties": {
          "key": "value"
        },
        "private_properties": {
          "key": "value"
        }
      }
    },
    "created_at": "2020-08-09T08:03:57Z",
    "version": "1"
  }
}

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","version":2,"user":{"id":"86954330754758633","idfa":"cce677ed-92c2-48aa-9b74-96a0eb0b12bb","identities":{"internal_id":"1314"}},"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":{"internal_id":"6536"}},"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
32
33
34
35
36
37
38
{
  "unique_id": "4feb25ef-64f7-4bd8-bc13-f3dd6657bb32",
  "version": 2,
  "user": {
    "id": "86954330754758633",
    "idfa": "cce677ed-92c2-48aa-9b74-96a0eb0b12bb",
    "identities": {
      "internal_id": "1314"
    }
  },
  "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": {
      "internal_id": "6536"
    }
  },
  "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?

😀 🙁