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

Go to ApiRTC Console > Company > Company account -> Settings -> WebHooks.

Webhooks configuration panel

• Filter on event type: Select the events which will trigger the webhook calls.

• URL: Set the URL which will be called by the webhook.

• Custom headers: In addition to filling in the URL field, you can add HTTP headers to the request (optional).

Don't forget to check the Activate checkbox !

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", "conversation", or "smsmessage"
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

Conversation

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”

SMS

object = "smsmessage"

No property is attached to the events of this object.

Conversation_event

object = "conversationevent"

Field	Description	Value
eventType	Type of event (e.g., media.OCRDone, ticket.new)	string (see list at Event Model)
eventCode	Digital code corresponding to the eventType.	integer
ticketId	ID of the ticket where the event occurred	integer
conversationId	ID of the conversation	integer
other fields...	depends on the event type. SeeSession Events APIfor a list of event types.

See Session Events API for more details on the event model.