Webhooks

Webhooks are a great way to trigger actions in 3rd party systems.

To get notified of some communication or platform events, ApiRTC can trigger WebHooks to your backend server.

WebHooks are triggered asynchronously.

To handle WebHooks, your backend needs to accept HTTP requests. When some event occurs, ApiRTC makes a POST HTTP request to the URL you have configured for your WebHooks.

The request includes details of the event. Your backend can then perform whatever logic is necessary.

To be notified of events, the Apizee solution offers a webhook, a notification that is made through an HTTP request. This request transmits an "event" object to the server. Only media, conversations, and tickets benefit from this feature.

Webhook Configuration

Set the URL that should be called by the webhook in the ApiRTC Console > Company > Company account -> Settings -> WebHooks. (and don't forget to check the Activate checkbox !)

webhook form

In addition to filling in the URL field (required if the Enable box is checked), you can add HTTP headers to the request (optional).

Events

An event is sent (POST method) to the Webhook URL.

The request is equivalent to the CURL command below:

curl --request POST 
-H "Content-Type: application/JSON" 
--data '{"event":"update",...}' 
https://my.domain.tld/apizeehooks/

Default Header (header)

User-Agent: Cloud Apizee

Events properties

The data sent is in JSON format and contains the following fields:

Properties	Description	Value Type
event	Name of the event	"create", "update", "delete"
time	UNIX timestamp at the time of the event	integer
object	Name of the target object	"ticket", "media" or "conversation"
objectId	Identifier of the target object	integer or uid depending on the object type
props	Properties of the target object. Depends on the target object (ticket, media, or conversation)

Example with a ticket object:

{
    "event": "update",
    "time": 1575976413,
    "object": "ticket",
    "objectId": 100,
    "props": {
        "state": "invited"
        }
}

Other example with a conversation object:

{
  "event": "update",
  "time": 1632144306,
  "object": "conversation",
  "objectId": "734e3a7b-eb17-4d3f-901d-bcff178b",
  "props": {
    "eventType": "conversationEnded",
    "name": "TEST",
    "finishedAt": "2021-09-20T13:25:06+00:00"
  }
}

Properties per object type

Ticket

object = ”ticket”

Name	Description	Values
state	Last recorded state	new, open, opened, invited, inprogress, updated, expired, declined, rejected, done, closed
geoloc.lat	Last recorded latitude	Example: 47.866675
geoloc.lng	Last recorded longitude	Example: -3.865805

Media

object = ”media”

Name	Description	Values
state	Last recorded state	inprogress, uncompleted, completed, error
_parent.name	Name of the parent object	ticket, conference, conversation
_parent.id	ID of the parent object	integer

Conference

object = “conversation“

Note: For this object, the object_id does not correspond to the database ID but to the public_id field in the database.

Name	Description	Values
eventType	Type of sent event	conversationEnded
name	Name of the conversation	string
finishedAt	End date of the conversation	string, Example: “2021-08-03T15:05:50+00:00”