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

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:

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:

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.

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:

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.

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:

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:

{"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:

{"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 dataecho$parsed["event"]." event received for user ".$parsed["user_id"];if(isset($parsed["referrer"]["id"])){echo", who was referred by ".$parsed["referrer"]["id"];}