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.

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 here.
`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¶

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

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

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¶

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

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

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

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

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

Export Data Event¶

This event is triggered when an export data request has been made through the GetSocial Dashboard inside Data Export → CSV Export or the HTTP API.

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
`event`	string	Name of the event. Set to `export_data`.
`query`	string	Name of the query that was requested for export. For a full list see the HTTP API
`rows`	number	Number of total rows exported.
`files`	array	Array of files that were generated by the export request
`duration`	number	Time it took for the export request to be handled, in milliseconds.

Sample webhook¶

{
  "timestamp": "2023-06-26T09:17:44Z",
  "unique_id": "e76c5a93-1213-4e97-b15a-febbbc0cef59",
  "event": "export_data",
  "version": 2,
  "query": "notification_templates",
  "rows": 608,
  "files": [
    "https://..."
  ],
  "duration": 36
}

Register Webhook URL¶

To register a webhook URL:

Login to your account on the GetSocial Dashboard.
Go to Data Export section → Webhooks tab.
Enter your Webhook URL and click the save icon in the lower right corner.
(Optional) For testing purposes you can use hookbin.com to create a temporary URL which you can use as a webhook.
(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:

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

Request Body:

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

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

PHP

<?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"];
}

Node JS

// 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?

😀 🙁

GetSocial Webhooks v2¶

Introduction¶

Versioning¶

Security¶

Webhook Details¶

App Install Event¶

Sample webhook¶

App Open Event¶

Sample webhook¶

Web Signup Event¶

Sample webhook¶

Web Open Event¶

Sample webhook¶

Smart Flows¶

Sample webhook¶

Activities Create / Update¶

Sample webhook¶

Activities Reactions¶

Sample webhook¶

Export Data Event¶

Sample webhook¶

Register Webhook URL¶

Sample Request and Validation¶

Give us your feedback! Was this article helpful?