Webhooks

Introduction

When an event occurs, an HTTP POST call is issued on the callback urls you set up with the event data. Data is sent with application/json header content-type, and json format as payload. Callback urls must be defined with HTTPS protocol and should be available with POST verb to send data payload. iAdvize expect to have à 20x http status in callback result.

Subscribe to your first webhook

In order to subscribe to the webhooks of your website, you need to create an app in our marketplace. You'll need to have a developer account that you can get by signing up on this page. You'll then be able to subscribe to all the available webhooks through our webhook building interface: iAdvize .

Conversation events description

Name	Channel	Description	Comment
`conversation.started`	`CALL`	Beginning of a call conversation	-
`v2.conversation.pushed`	`CHAT`,`VIDEO`	Beginning of a chat conversation or receiving of a conversation transferred by another operator.	Replace the use of old deprecated events (conversation.started and conversation.transferred)
`v2.conversation.closed`	Onsite: `CHAT`, `CALL`, `VIDEO` Offsite: `FACEBOOK`, `FACEBOOK_BUSINESS_ON_MESSENGER`, `TWITTER`, `MOBILE_APP`, `SMS`	End of a conversation. Conversations on offsite channels are automatically closed after 7 days of inactivity	Replace the use of old deprecated event (conversation.closed)
`visitor.updated`		Visitor information updated from desk or admin view

Examples of payload for conversation events

Output examples of Conversations domain:

Please note :

Attribute	Description
clientId	As a client of iAdvize you have a specific ID, it is what this one represents
visitorId	Each visitor has a unique ID. iAdvize calls it visitor unique ID

conversation.started (only for call channel)

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "conversation.started",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 1,
    "operatorId": 1,
    "channel": "call",
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

visitor.updated

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "visitor.updated",
    "platform": "sd",
    "clientId": 1,
    "operatorId": 1,
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

We are currently migrating our events to a new format to offer you more flexibility in the way you can query our data. With V2 events, you can query the corresponding resources through our GraphQL api.

Payload examples of v2 conversation events

v2.conversation.pushed

{
  "eventId": "0f0bb3af-5035-4ba3-b3fb-ff4879a3a74d",
  "eventType": "v2.conversation.pushed",
  "platform": "ha",
  "projectId": 1549,
  "clientId": 335,
  "conversationId": "4c8c7408-f73c-42cd-89e9-afbbee7d9024",
  "operatorId": 15253,
  "visitorExternalId": "63429889",
  "channel": "CHAT",
  "createdAt": "2019-04-12T07:58:35.171Z",
  "sentAt": "2019-04-12T07:58:35.496Z"
}

v2.conversation.closed

{
  "eventId": "0f0bb3af-5035-4ba3-b3fb-ff4879a3a74d",
  "eventType": "v2.conversation.closed",
  "platform": "ha",
  "projectId": 1549,
  "clientId": 335,
  "conversationId": "4c8c7408-f73c-42cd-89e9-afbbee7d9024",
  "operatorIds": [
    15253,
    15254
   ],
  "visitorExternalId": "63429889", //or null for offsite channels such as Facebook
  "channel": "CHAT",
  "createdAt": "2019-04-12T07:58:35.171Z",
  "sentAt": "2019-04-12T07:58:35.496Z"
}

Deprecated conversation events

WARNING: the following events should not be used anymore, they still appear in this documentation only for history purposes!

conversation.started for channel chat

PLEASE DO NOT USE (refer to warning above).

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "conversation.started",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 1,
    "operatorId": 1,
    "channel": "chat",
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

conversation.transferred

PLEASE DO NOT USE (refer to warning above).

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "conversation.transferred",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 2,
    "transferredConversationId": 1,
    "operatorId": 1,
    "channel": "chat",
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

conversation.closed

PLEASE DO NOT USE (refer to warning above).

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "conversation.closed",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 1,
    "operatorId": 1,
    "channel": "chat",
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

User events description

Domain	Name
`user.created`	User created
`user.updated`	User information updated
`satisfaction.filled`
`user.connected`
`user.disconnected`

Payloads

user.created

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "user.created",
    "platform": "sd",
    "clientId": 1,
    "userId": 1,
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

user.updated

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "user.updated",
    "platform": "sd",
    "clientId": 1,
    "userId": 1,
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

HTTP stack trace example for “conversation.closed” event

POST /webhook HTTP/1.1

Host: localhost
X-iAdvize-Signature: sha256=110e8400-e29b-11d4-a716-446655440000
X-iAdvize-CorrelationId: 332e8400-e34b-11d4-a716-446655444444
X-iAdvize-Delivery: 110e8400-e29b-11d4-a716-446655440000
Content-Type: application/json
Content-Length: 3442

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "conversation.closed",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 1,
    "operatorId": 1,
    "channel": "chat",
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

Deprecated user events

WARNING: the following events should not be used anymore, they still appear in this documentation only for history purposes!

satisfaction.filled

PLEASE DO NOT USE (refer to warning above).

{
    "eventId": "d36cd3c4-2d16-4a77-97c2-620bde859b29",
    "eventType": "satisfaction.filled",
    "platform": "sd",
    "websiteId": 1,
    "clientId": 1,
    "conversationId": 1,
    "operatorId": 2,
    "visitorId": "593de0891b628a50b09835dc6c0e92565329c74baa90e",
    "score": 3,
    "createdAt": "2017-04-22T11:01:00+02:00",
    "sentAt": "2017-04-22T11:01:00+02:00"
}

Delivery headers

iAdvize will send payload with three additional headers:

X-iAdvize-Delivery: UUID, unique identifier to describe this webhook delivery
X-iAdvize-CorrelationId: UUID, event identifier used in retry webhooks to track same callback calls.
X-iAdvize-Signature: Hash signature, cf. Security section

Webhook retry management

If errors occur during webhook query (40x, 50x http status codes), we will retry two times. We will try to send you the following requests:

First time after delay of 10 seconds,
and second time after 20 seconds (so, 30 seconds after first call).

In case of failure, you may need to track events in error, by following "X-iAdvize-CorrelationId" in headers, or "eventId" in payload.

Webhook security

Please refer to this section.