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 !)

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:

PropertiesDescriptionValue 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”

NameDescriptionValues

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”

NameDescriptionValues

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.

NameDescriptionValues

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”

Last updated