An Early Access Program allows you to get an early preview of what we are building and help us improve it before we make it a permanent part of Dixa. 

Read more about Early Access Programs

Important customer engagement events happen in Dixa everyday and for some events it can be key that you react to them in real-time. With the new conversation webhooks feature you can now subscribe to events in Dixa and have them trigger work flows in any of your other tools.

  • Quick setup - Create subscriptions for conversation events easily
  • No clutter - Choose the events that your business cares about
  • Real-time - Empower your business with real-time updates about your Dixa conversations

Sign up

You should make sure to read the documentation about limitations and known bugs below to understand what you are signing up for. Once signed up, we will be checking in with you to get feedback allowing us to improve the functionality. If you are not prepared for giving us feedback, we recommend that you wait until it’s a permanent part of the Dixa product.

Sign up here

We will inform you via email when your account has been added to the Early Access Program.


Common Webhooks use cases

Webhooks are commonly used to get near real-time updates about events in one system to another system. So Dixa's conversation event webhooks can be used to e.g.:

  • update your CRM system (either directly or via Zapier) so that customer contact events that happen in Dixa can also be registered in your CRM
  • send conversation events to Slack, so that you can get a near real-time picture of what is happening in your customer service department


Setup for Webhooks in Dixa

In order to set up the foundation to use the new conversation webhooks you need to be a Dixa administrator, because you need to be able to access the settings of your organisation in Dixa.

1. Go to Settings > Integrations > Webhooks

2. Choose "Add webhook"

3. Fill in the required details:

  • Name: Type a name here, so you can recognise your webhook easily later.
  • Events to subscribe to: Select the events you are interested in getting delivered to your systems. You can read about the available event types and payloads further below.
  • Webhook URL: Specify the URL that the events should be sent to. This could be an API from your internal system or e.g. a CRM like salesforce.
  • Headers: Specifying additional headers is optional but might be required by your system in order to digest the incoming webhooks.

4. Choose "Add" to save the new webhook
 and reveal the option to copy the verification secret for it.

Now your first webhook subscription is in place and you can finalize the setup on your end to make sure that you can receive events from Dixa.

Verification process

To get an X-DIXA-SIGNATURE header, it should contain 2 comma-separated key-value pairs: 

"t=<timestamp>,v1=<signature>"

To verify the signature, you can create `signed payload` using following concatenation:

    -the timestamp (as a string)
    -the character .
    -the actual JSON payload

To apply the HMAC verification on the `signed payload`, use the secret key.

As for our implementation, we use javax.crypto and a SHA256 algorithm. The secret key is HEX encoded and needs to be decoded being used in HMAC. The output signature is HEX encoded as well. 

Headers and authentication

By default Dixa will include the following headers when delivering a webhook. These headers cannot be overwritten:

X-DIXA-SIGNATURE : <SECRET TOKEN> [To verify the requests],
X-DIXA-SUBSCRIPTION-ID : “beabb3e2-3a10-4a44-9a88-9359887a139f” [A Unique Subscription ID]
Content-Type : “application/json” [Constant]

It is possible to add additional headers if needed and adding a basic authentication header is also supported in the UI:

More details on basic authentication can be read here.


Available event types and payloads


Event types:

  • Conversation created: Receive a webhook every time a conversation is created inside Dixa
  • Conversation enqueued: Receive a webhook every time a conversation enters a queue in Dixa
  • Conversation status changed: Receive a webhook every time a conversation changes its status between being open, closed or in follow-up (pending).
  • Conversation assigned: Receive a webhook every time a conversation gets assigned to an agent.

Each webhook will have the following payload: 

{
  “event_id”: “09785189-6ca3-4ec6-adc4-c1f1571e421d”,
  “event_fqn”: “CONVERSATION_STATUS_CHANGED”,
  “event_version”: “1",
  “event_timestamp”: “2020-02-03T19:20:31.601Z”,
  “data”: {
    “csid”: 90066,
    “channel”: “PSTN_PHONE”,
    “status”: “CLOSED”,
    “created_at”: “2020-02-03T19:19:49.467Z”,
    “queue_id”: “6caa258e-f38b-46be-8a8b-8ba007f633ad”,
    “queue_name”: “MyQueue”,
    “direction”: “INBOUND”,
    “requester_name”: “Requester Name”,
    “requester_email”: requester@dixa.com,
    “requester_phone”: “+4523895628”,
    “requester_avatar_url”: “https://upload.wikimedia.org/wikipedia/en/thumb/6/62/Kermit_the_Frog.jpg/220px-Kermit_the_Frog.jpg”,
    “assignee_name”: “Assignee Name”,
    “assignee_email”: “asignee@dixa.com”,
    “assignee_avatar_url”:https://upload.wikimedia.org/wikipedia/en/thumb/6/62/Kermit_the_Frog.jpg/220px-Kermit_the_Frog.jpg”,
    “tags”: [
      
    ]
  }
}

Please note that the payload structure is subject to change in the course of the Early Access Program.

Possible values in the payloads:

  • For event_fqn: CONVERSATION_STATUS_CHANGED, CONVERSATION_CREATED, CONVERSATION_ENQUEUED, CONVERSATION_ASSIGNED
  • For channel: CALLBACK, CONTACT_FORM, EMAIL, FACEBOOK_MESSENGER, PSTN_PHONE, SMS, UNKNOWN, VOICEMAIL, WHATS_APP, WIDGET_CHAT
  • For status: AWAITING_PENDING, CLOSED, OPEN, PENDING, UNKNOWN
  • For direction: INBOUND, INTERNAL, OUTBOUND, UNKNOWN


Best practice behavior

  • Handling duplicate events: Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts. One way of doing this is by logging the events you have processed, and then not processing already logged events again.
  • Order of events: While we are working with our best effort, we cannot guarantee the delivery of events in the order in which they are generated. Therefore your endpoint should not expect the delivery of these events in the order of occurrence and should handle this accordingly.
  • Security: Keeping your endpoints secure is critical to protecting your customers' information. Therefore we include a shared secret for verification in each event that is sent to you, so you can ensure that the event is indeed from Dixa and not a third party. You can find the verification secret for each of your webhook subscriptions by going to Settings > Integrations > Webhooks and then choose "Copy verification secret".
  • Retry logic: We will retry to deliver your webhooks every 10 minutes for up to 14 days or at the most 144 times, which means that if the rate of 10 minutes is kept we will retry for 24 hours.


Limitations

Webhooks only supports a selection of conversation events, to begin with. With your feedback, we plan to offer more event types in the future. Please also note that the payload structure is subject to change in the course of the Early Access Program.

Known bugs

None at the moment.