Webhooks
Last updated: 1st June, 2021
Use webhooks to build custom integrations. Anything that would normally trigger a notification, can be used to post a webhook to a specified URL.
- Traffic Spike/Dip – payload contains the number of visitors currently on your site and a summary of your site's traffic info.
- User enters/exits a Smart Group – payload contains the full profile info and the name of the group they entered/exited.
- New message – payload contains the chat message and profile information about the user who sent it.
GoSquared will issue an HTTP POST request to the URL you specify with a JSON payload containing details of the triggered notification.
Setting up a Webhook
Log in to GoSquared and go to Setting > Current Project > Integrations.
Add a Webhook service (don't forget to give it a memorable name) and paste the URL that will receive the HTTP POST request.
Next, navigate to the Notifications tab in your Project Settings. Here you will be able to configure which notification types should send a Webhook.
Either add a new notification or edit an existing one, and select the Webhook service in the delivery options.
Note: there is currently no way to manually post a Webhook – you have to trigger a Webhook by creating the conditions that you set in your notification (i.e. set a traffic spike of greater than 1 visitor on the site, or create a test smart group that checks filters for last seen within the last 5 minutes).
Smart Group Webhooks (People)
These are useful for triggering an action in a 3rd party application/service. For example, when a user enters your 'Latest Signups' Smart Group – send a Webhook to your CRM to add them as a contact.
Each Webhook is sent with a semver compliant version number in the version property of the JSON object. Your code should check this property when processing each Webhook request to ensure it is compatible. We do not make breaking changes frequently, but if we do we will notify anyone set up to receive Webhooks in advance.
Example JSON payload:
{
"version": "0.0.1",
"site_token": "GSN-663002-A",
"timestamp": "2021-06-01T11:05:18.726Z",
"group": {
"id": "new-user",
"name": "new user"
},
"boundary": "enter",
"person": {
"id": "46328",
"name": "Russell Vaughan",
"given_name": "Russell",
"family_name": "Vaughan",
"email": "russell@gosquared.com",
"description": "Leadership, Growth, Strength, Dynamic Ability",
"avatar": "https://randomuser.me/api/portraits/men/42.jpg",
"phone": "555-555-5555",
"created_at": "2013-10-27T14:50:09.000Z",
"company": {
"name": "GoSquared",
"industry": "SaaS",
"position": "Sales Engineer"
},
"first": {
"seen": "2017-11-09T16:49:23.828Z",
"page": {
"path": "/pricing",
"title": "Pricing Page"
},
"referrer": {
"type": "social",
"domain": "facebook.com",
"href": "https://www.facebook.com"
},
"campaign": {
"name": "Paid Social",
"medium": "Social",
"source": "Facebook",
"content": "",
"text": ""
}
},
"last": {
"seen": "2021-06-01T11:05:07.075Z",
"page": {
"path": "/register",
"title": "Register"
},
"visit": "2021-06-01T11:05:07.075Z",
"exit": "2021-06-01T10:32:14.258Z",
"ip": "80.169.94.194",
"organisation": "COLT Technology Services Group Limited",
"language": "en-gb",
"device": "119629-2",
"location": {
"timezone_offset": 0,
"city": "London",
"region": "ENG",
"country": {
"name": "United Kingdom",
"code": "GB"
},
"continent": "EU",
"coordinates": [
51.5164,
-0.093
]
}
},
"totals": {
"visits": 70,
"pageviews": 342,
"engaged_time": 5675,
"time_on_site": 3454335
},
"social": {
"profiles": [
{
"photo": "",
"bio": "Sales Engineer @ GoSquared",
"following": 119,
"type": "twitter",
"url": "https://twitter.com/russellvaughan",
"followers": 1486,
"username": "russellvaughan",
"name": "Twitter"
},
{
"bio": "",
"type": "linkedin",
"url": "https://www.linkedin.com/in/russell-vaughan-6169a248/",
"username": "russell-vaughan-6169a248",
"name": "Linkedin"
}
],
"klout": {
"score": 44
},
"updated": "2017-11-08T12:09:16.161Z"
},
"custom": {
"Plan": "Basic",
"NPS": "9",
"lead_score": "10",
},
"events": {
"Downloaded white paper": {
"count": 3,
"first": "2019-10-18T16:54:52.888Z",
"last": "2020-10-18T16:54:52.888Z"
},
"Requested a demo": {
"count": 1,
"first": "2020-01-15T17:00:03.279Z",
"last": "2020-01-15T17:00:03.279Z"
},
"Signed up to newsletter": {
"count": 1,
"first": "2020-11-09T17:11:09.693Z",
"last": "2020-11-09T17:11:09.693Z"
}
},
"status": "customer",
"avatar_secure": "https://avatars.gosquared.com/5194019672e7688ba8b05013234af656be6ea40f/68747470733a2f2f72616e646f6d757365722e6d652f6170692f706f727472616974732f6d656e2f34322e6a7067",
"emailVerified": true
}
}
Traffic Spike / Dip Webhooks (Analytics)
Example JSON payload:
{
"concurrents": 1234, // Total number of visitors on the site at the time of the alert
"triggeredAlert": { ... }, // Details of the specific alert that was triggered
"siteDetails": { ... }, // Summary details of the site against which the alert was triggered
"snapshot": { // Snapshot of the site's traffic data at the time of the alert,
"time": { ... }, // all keys contain the equivalent data returned by the corresponding
"concurrents": { ... }, // function in the Now API
"pages": { ... }
"sources": { ... },
"engagement": { ... },
"timeSeries": { ... }
}
}
New Message (Assistant)
Example JSON payload:
{
"version": "0.0.1",
"site_token": "GSN-123456-A",
"timestamp": "2021-03-09T17:35:48.180Z",
"person": {
"id": "Anon Chat: 6a691ccaf6b7d7842d1f60d75862ea1d",
"email": "",
"name": "Russell Vaughan",
"avatar": "",
"chat": {
"archived": null,
"latest": {
"message": {
"type": "message",
"id": "384ddf9e-38b1-4fca-9dcd-1f0da130df6d",
"content": "Hello World",
"timestamp": 1615311348180,
"from": "client",
"private": false,
"session": {
"title": "Example Website",
"href": "http://www.example.com/"
},
"data": {},
"entities": []
},
"timestamp": 1615311348180
},
"agent": {
"assigned": null,
"read": 1614101467720,
"delivered": 1614101103697
},
"client": {
"read": 1615311348180,
"delivered": 1615311348180
},
"language": "en",
"translationPaused": false
},
"lead": {
"email": "email@example.com"
},
"status": "lead",
"presence": "online",
"_anon": {
"name": "Anon: Curious Blue Brain",
"color": "#3498DB",
"shape": "brain-speech-bubble"
},
"deleted": false,
"_links": [
{
"rel": "self",
"href": "https://api.gosquared.com/chat/v1/chats/Anon%20Chat%3A%206a691ccaf6b7d7842d1f60d75862ea1d",
"method": "GET"
}
]
},
"message": {
"type": "message",
"id": "384ddf9e-38b1-4fca-9dcd-1f0da130df6d",
"content": "Hello World",
"timestamp": 1615311348180,
"from": "client",
"private": false,
"session": {
"title": "Example Website",
"href": "http://www.example.com/"
},
"data": {},
"entities": [],
"person_id": "Anon Chat: 6a691ccaf6b7d7842d1f60d75862ea1d"
}
}