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" }
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.
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:
In order to complete the verification successfully, the request is expected to return:
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.
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 }
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 { }
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 | ✘ |