There are certain Messenger API events that can trigger an HTTPS POST request to an external service via a webhook.
In addition, certain events occurring within the Messenger instance can also trigger an HTTPS POST request to an external service via a webhook.
This article provides information on both types of webhooks, including how to set them up, which events to subscribe to and what payloads they use.
Messenger API webhooks are the webhooks that can be triggered by certain Messenger API events, which are listed in the section below.
Before adding a webhook, you must first decide the type of events you want to subscribe to:
| Item/event type | Description |
|---|---|
| alert | When an alert is added to a ticket |
| ticket | When a (sub)ticket is added or updated |
| reply | When a reply is added to a ticket |
| user | When a user is added or updated |
| media | When a media file is added to a ticket |
| classification | When a classification is added to or removed from the Messenger instance |
| queue | When a queue is added or updated in the Messenger instance |
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 payload of the POST request sent to the webhook URL differs depending on the event that has triggered the request.
Each payload contains the following information:
For example:
{
'id': 200, // id of the reply
'item': 'reply',
'action': 'add',
'timestamp': 1660834225,
'actor': 4014,
'parent': 100,
}
The following table presents a summary of which endpoint produces a webhook, depending on the item and subscribed action. If the Endpoint column is empty, this means the corresponding action does not produce a webhook request.
| 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 | POST /users |
| update | PUT /users/{userId} | |
| 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 | ✘ |
You can retrieve a list of all the active webhooks by calling the following endpoint:
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
{
}
Messenger instance webhooks are webhooks you can configure in the Messenger instance itself or by using the Messenger API’s POST /webhooks/app endpoint. This type of webhook can be triggered by each of the events listed below.
Before adding a webhook, you must first decide the type of events you want to subscribe to.
You have the following options
| Event | Description |
|---|---|
| answer |
The webhook is triggered when an agent answers a ticket in the Messenger instance. |
| create-ticket |
The webhook is triggered when a ticket is created in the Messenger instance. This does not include tickets created by the Messenger API. |
| create-subticket |
The webhook is triggered when a subticket is created in the Messenger instance. |
| close-ticket |
The webhook is triggered when a ticket is closed in the Messenger instance. |
| classify-ticket |
The webhook is triggered when a ticket is (re)classified in the Messenger instance. |
| change-queue |
The webhook is triggered when a ticket in the Messenger instance is moved to a different queue. |
| reply-ticket |
The webhook is triggered when an end user replies to a ticket in the Messenger instance. |
Before a webhook can be added to the Messenger instance, you need to set up your server to be able to receive Inbenta requests and create the Webhook URL. Make sure you also obtain the secret to the Webhook URL.
To set up your server to receive Inbenta requests:
Whenever you add a new webhook to your Messenger instance, Inbenta sends a GET request to the webhook endpoint (URL) with an automatically generated code in the X-Inbenta-Challenge header. The endpoint should return a 200 (OK) response together with the same header and the received code. This header will only be sent once for each webhook, upon the webhook's creation in your instance. For more information on handshakes, please check out the relevant documentation on the Developers' Portal.
Then, once the webhook has been configured in the Messenger instance as instructed in this article, each time the selected events occur, a POST request is sent to the webhook URL with the secret in the X-Hook-Signature HTTPS header for validation, and the payload(s) corresponding to those events. You can find the information that will be sent in each payload in the Payloads section below.
Note that the payload of each request contains the data that was accurate right after the action was completed. Even though the data may have already changed by the time we send the request, it can be used to know the status of the resource right after the action was completed.
Each webhook request will include only the information that was changed through a specific action. If you want to obtain the actual status of a ticket at a certain time in case the information received through the webhook has already changed, send a request to the Messenger API.
The payload of the POST request sent to the webhook URL differs depending on the event that has triggered the request. Below, you can find which event triggers which payload to be sent.
Each payload contains at least the following information:
# Request to your server
POST /path/to/receive-webhook/
X-Hook-Signature: yourOwnSecretCode
{
"events": [{
"id": "MDAwMDAwMOSfti9quwKNOg==",
"action": "answer",
"created_at": "20170905091635",
"resource": "PROJECTNAME-00110063",
"type": "ticket",
"user": {
"name": "name",
"identifier": "email@email.com"
},
"action_data": {
"text": "text",
"to": [{
"email": "email@email.com",
"name": "name"
}],
"cc": null,
"bcc": null
},
"resource_data": {
"creator": {
"name": "name",
"identifier": "email@email.com"
},
"queue": {
"id": 1,
"name": "queue_name"
},
"source": {
"id": 1,
"name": "source_name"
}
},
"project": {
"name": "instance_name"
},
"attachments": [{
"id": "123",
"url": "image_url",
"name": "Image name.png",
"type": "image\/png",
}],
}]
}
The ANSWER payload contains the following information:
# Request to your server
POST /path/to/receive-webhook/
X-Hook-Signature: yourOwnSecretCode
{
"events": [
{
"id": "MDAwMDAwMOSfti9quwKNOg==",
"action": "create-ticket",
"created_at": "20170905091635",
"project": "project_name",
"body": {
"ticket_id": "PROJECTNAME-00110063",
}
}
]
}
The “body” property of the CREATE TICKET payload contains the following information:
# Request to your server
POST /path/to/receive-webhook/
X-Hook-Signature: yourOwnSecretCode
{
"events": [
{
"id": "MDAwMDAwMOSfti9quwKNOg==",
"action": "create-ticket",
"created_at": "20170905091635",
"project": "project_name",
"body": {
"ticket_id": "PROJECTNAME-00110064",
"parentId": "PROJECTNAME-00110063",
}
}
]
}
The “body” property of the CREATE TICKET payload contains the following information:
parentId: The ID of the parent ticket
# Request to your server
POST /path/to/receive-webhook/
X-Hook-Signature: yourOwnSecretCode
{
"events": [
{
"id": "BViqcuixKxgwAETmUHSsdsS==",
"action": "change-queue",
"created_at": "20170908114619",
"project": "project_name",
"body": {
"ticket_id": "PROJECTNAME-00110063",
"previous_queue": 1,
"new_queue": 2,
}
}
]
}
The “body” property of the CHANGE QUEUE payload contains the following information:
You can find the queue names and IDs in Messenger > Settings > Queues.
# Request to your server
POST /path/to/receive-webhook/
X-Hook-Signature: yourOwnSecretCode
{
"events": [
{
"id": "BViqcuixKxgwAETsECasdG==",
"action": "classify-ticket",
"created_at": "20170908115131",
"project": "project_name",
"body": {
"ticket_id": "PROJECTNAME-00110063",
"previous_classification": "",
"new_classification": "3,6,10,32",
}
}
]
}
The “body” property of the CLASSIFY TICKET payload contains the following information:
# Request to your server
POST /path/to/receive-webhook/
X-Hook-Signature: yourOwnSecretCode
{
"events": [
{
"id": "BViqcuixKxgwAETmVyaseE==",
"action": "reply-ticket",
"created_at": "20170908115131",
"project": "project_name",
"body": {
"ticket_id": "PROJECTNAME-00110063",
"message": {
"content": "\tHTML text\n<\/p>",
"from": {
"id": 15789,
"name": "Agent\u00a0Name",
"address": "username@example.com",
"external_id": null,
"is_agent": true,
},
"attachments": [
{
"id": "641",
"url": "image_url",
"name": "Image name.png",
"type": "image\/png"
}
],
},
}
}
]
}
The “body” property of the REPLY TICKET payload contains the following information:
# Request to your server
POST /path/to/receive-webhook/
X-Hook-Signature: yourOwnSecretCode
{
"events": [
{
"id": "BViqumc58C4XI+K8N31HQQ==",
"action": "close-ticket",
"created_at": "20170908115131",
"project": "project_name",
"body": {
"ticket_id": "PROJECTNAME-00110063",
"status": 3,
}
}
]
}
The “body” property of the CLOSE TICKET payload contains the following information: