Socialboards
  • Developer hub
  • APIs
    • Ticket API
      • Getting Started
        • Guidelines and data privacy
      • Authorization
        • Access tokens
      • Categories
      • Custom Fields
      • Action Log
      • Notes
      • Replies
      • Tags
      • Tickets
      • Teammates
      • User Groups
      • Widgets
      • Webhooks
        • Getting Started
        • Create Endpoint
        • Configure the Webhooks
        • Testing your webhooks
      • Reference
        • Endpoints
          • Get Access Token v2
          • Get Full Community Category List
          • Get Subcategories by Parent Id
          • Get Category By Id
          • Get Full Community Custom Field List
          • Add Custom Field
          • Get Custom Field
          • Get All Teammates
          • Get All User Groups for Community
          • Update Custom Field
          • Delete Custom Field
          • Create Ticket
          • List Tickets
          • List Ticket Ids By Field Ids
          • Get Ticket by Id
          • Update Ticket Custom Field Value
          • Update Ticket Assignee
          • Get Ticket Log
          • Update Ticket Status
          • Update Ticket Category (Obsolete)
          • Update Ticket Category
          • Create Reply
          • List Replies
          • Add Note To Ticket
          • Update Note
          • Delete Note
          • List tags
          • Replace Ticket Tags
          • Replace Reply Tags
          • Get Widget Schedule List
        • API Request Result
        • Webhook Payload
        • Objects
          • Base Attachment
          • Category
          • Custom Field
          • Custom Field Id with Value
          • Custom Field Possible Value
          • Custom Field Value
          • Custom Times Widget Schedule
          • Note
          • Reply
          • Reply/Note Creator
          • Reply Properties
          • Schedule Time
          • Tag
          • Teammate
          • Ticket
          • Ticket Action Included Items
          • Ticket Creator
          • Ticket Id with Field Value
          • Ticket Log
          • Ticket Properties
          • User
          • User Group
          • Widget Schedule
        • Events
          • Ticket Creation
          • Ticket Status Change
          • Ticket Tags Change
          • Ticket Category Change
          • Reply Creation
          • Reply Update
          • Reply Deletion
          • Note Creation
          • Note Update
          • Note Deletion
        • Enumerations
          • Custom Field Types and Values Formats
          • Sentiment
          • Ticket Action Type
          • Ticket List Order By
          • Ticket Source
          • Ticket Status
          • User Role
          • Detailed Ticket Source
      • Glossary
    • External Chat API
      • Conversations Overview
      • Configure the Webhooks
      • Glossary
      • Reference
        • Endpoints
          • Create conversation
          • Add messages to conversation
          • Get conversation by id
          • List conversation messages
          • Get conversation queue information
          • Get takeover state
          • Change takeover state
          • Update conversation feedback
          • Update conversation latest url
          • Close conversation
        • Objects
          • Bot
          • Conversation
          • Conversation feedback
          • Conversation message
          • Conversation takeover
          • Conversation queue position
          • User
          • User Value
        • Events
          • Conversation created
          • Conversation Message Added
          • Conversation Takeover State Changed
          • Conversation Status Changed
        • Enumerations
          • Bot type
          • Order by
          • User status
          • Conversation Status
    • FAQ API
      • Glossary
      • Categories
      • FAQ Instances
      • Tags
      • Topics
      • Reference
        • Endpoints
          • List FAQ Instances
          • List Tags
          • List Categories
          • List Topics
          • Get Specific Topic
          • Add Vote to Topic
          • Increase View Count for Topic
          • Search Topics by Params
        • Objects
          • Attachment
          • Category
          • Instance
          • Tag
          • Topic
          • Topic Search Result
        • Enumerations
          • Localization Language
          • Template Type
          • Topic Downvote Reason
          • Topics Sort Options
    • Support Widget
      • Installation
      • Configuration options
      • Full script example
      • Javascript changelog
      • Widget schedule API
    • Reporting & Statistics
      • Data warehouse (DWH)
        • Entity relationship diagram (ERD)
        • Most used views and values
      • Reports and dashboards
  • Security
    • Introduction to Security
    • Data centers & network security
    • Product security features
    • Application security
    • Data Processing
    • Sub-Processors
      • 2023-04 Intility AS
        • Addendum 2023-4
  • Updates
    • Changelog
Powered by GitBook
On this page

Was this helpful?

  1. APIs
  2. Ticket API
  3. Webhooks

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": "robert78baker@gmail.com",
					"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
		}
	]
}

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.

PreviousGetting StartedNextConfigure the Webhooks

Last updated 1 year ago

Was this helpful?

More info about event payload structure you can get in the

following document.