Webhooks

Subscribe to webhook events

In order to add a webhook, you must first decide the type of events you want to subscribe to:

Item Description
alert Case alert events
ticket Case events
reply Case conversation events
user User events
media File uploads
classification Classification settings events
queue Queue settings events

Once you know the type of events that you want your webhook to receive, you must register the receiving URL:

 POST /v1/webhooks HTTP/1.1
 Content-Type: application/json
 {
    "item": "ticket",
    "url": "https://some.example/endpoint"
    "secret": "SomeRandomString"
 }
 

Caution: The URL must use the 'https' protocol

The response to this call will be the uuid of the webhook that can update or even delete it.

Important: When it performs the above POST call, the system also runs a verification test to make sure that the URL belongs to you. If the test fails, the webhook creation fails too.
The verification consists of an empty GET request to the specified URL, with two relevant headers:

  • "X-Hook-Signature": This header contains the previously specified secret.
  • "X-Inbenta-Challenge": This contains a random string.

In order to complete the verification successfully, the request is expected to return:

  • HTTP code: 200
  • Body: The content of the "X-Inbenta-Challenge" header as plain text

Note: If you want to send multiple webhook item events to the same URL, add a new webhook for each with its own item and the same URL.

Receive webhook events

The system always sends a list of webhook events. It can contain one or multiple webhook events and it always groups objects in batches as much as possible to reduce the number of requests .
Each webhook event has the following structure:

 {
    "id": integer,
    "item": string ["alert","ticket","reply","user","media","classification"],
    "action": string ["add","update","remove"],
    "timestamp": integer,
    "actor": integer,
    "parent": integer|null
 }
 
Field Description
id The id of the item that triggered this event
item The type of item that the id provided represents
action The type of action the item experienced
timestamp The time the action took place
actor id of the user who triggered the action
parent (If any) The id of the parent object related to the item

Example: Creating a new classification

 {
    "id": 123, // The id of the created classification
    "item": "classification",
    "action": "add",
    "timestamp": 1524149939,
    "actor": 123, // Timestamp of the creation of the classification
    "parent": 5 // The id of the parent classification
 }
 

Update/Delete webhook subscriptions

You can retrieve a list of all the active webhooks:

 GET /v1/webhooks HTTP/1.1
     Accept: application/json
 {
 }
 

You can update any webhook field at any time using its id:

 PUT /v1/webhooks/{id} HTTP/1.1
 Content-Type: application/json
 {
    "item": "ticket",
    "url": "https://some.example/endpoint"
    "secret": "SomeRandomString"
 }
 

If a webhook is no longer necessary, you can delete it instantly using its id:

 DELETE /v1/webhooks/{id} HTTP/1.1
 Accept: application/json
 {
 }
 

Annex

The following table presents a summary of which endpoint produces a webhook, depending on the item and subscribed action.

Item Action Endpoint
alert add POST /tickets/{ticketId}/alerts
update
remove
ticket add POST /tickets
POST /tickets/{ticketId}/subtickets
update PUT /tickets/{ticketId}
remove
reply add POST /tickets/{ticketId}/replies
update
remove
user add
update
remove
media add POST /media
update
remove
classification add POST /classifications
update
remove DELETE /classifications/{classificationId}
queue add POST /queues
update PUT /queues/{queueId}
remove