Create Endpoint

Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.

The sections below explain what will be in each type of request and how to respond to them.

Verification Requests

Anytime you configure the Webhooks product in your community settings page, we'll send a GET request to your endpoint URL. Verification requests include the following query string parameters, appended to the end of your endpoint URL. They will look something like this:

GET https://www.your_domain_name.com/webhooks?
  challenge=2135675231&
  verifyToken=someverificationtoken

Validating Verification Requests

Whenever your endpoint receives a verification request, it must:

• Verify that the verifyToken value matches the string you set in the Verify Token field when you configure the Webhooks product in your community settings.

  (you will set up this token during configuring webhooks).

• Respond body should should contain challenge value.

Event Notifications

When you configure your Webhooks product, you will subscribe to specific events on an object type (e.g., the status change event on the ticket object). Whenever such event happened, we will send your endpoint a POST request with a JSON payload describing the change. For example, let's say you set up a “Ticket”

Webhook and subscribed to “Status changed” event. If ticket’s status was changed from “open” to “pending”, we'd send you a notification that would look like this:

{
	"CommunityName": "yourCompany",
	"EventType": "ticket_status_change",
	"Events": [
		{
			"InboxLink": "https://inbox.socialboards.com/yourCompany/tickets?ticketId=4478963",
			"PreviousTicketStatus": "open",
			"Ticket": {
				"Author": {
					"Id": "35692164-bfaa-4c49-a23c-ecfa618f7d20",
					"Name": "Robert Baker",
					"Image": null,
					"Email": "[e-mail]",
					"Status": "client",
					"IsBot": false
				},
				"Category": {
					"Id": 15721,
					"Name": "Other cases",
					"Parents": []
				},
				"CreationTime": "2019-12-17T08:03:48.318717+01:00",
				"DetailedSource": "web_website",
				"Id": 4478963,
				"LastThreadElementCreationTime": "2019-12-17T08:10:03.8181291+01:00",
				"LockedBy": null,
				"Message": "I want to take my cat to a vet",
				"OriginalLink": null,
				"Properties": {
					"IsAnonymized": false,
					"IsMuted": false,
					"HasAttachments": false,
					"HasDraft": false,
					"IsAssignedToBot": false,
					"IsDeleted": false,
					"IsExpired": false,
					"IsHidden": false,
					"IsLocked": false,
					"IsSpam": false,
					"IsSensitive": false
				},
				"ReplyCount": 1,
				"Sentiment": "question",
				"Source": "web",
				"SourceName": null,
				"Status": "pending",
				"Title": "Cat is ill",
				"HtmlMessage": "I want to take my cat to a vet"
			},
			"TicketId": 4478963
		}
	]
}

Payload Contents

We format all payloads with JSON, so you can parse the payload using common JSON parsing methods or packages.

We do not store any Webhook event notification data that we send you, so be sure to capture and store any payload content that you want to keep.

The structure of the JSON body you receive, will look like this:

{
	"CommunityName": "yourCompany",
	"EventType": "note_deletion",
	"Events": [
		{
			"NoteId": 182605
		}
	]
}

More info about event payload structure you can get in the following document.

Responding to Event Notifications

Your endpoint should respond to all Event Notifications with 200 OK HTTPS. Your endpoint should respond to all webhook events in 20 seconds or less.