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 every day and for some events, it can be key that you receive notifications of an update in real-time so that you can react immediately. With our webhooks, you can now subscribe to all conversation events in Dixa and have them trigger workflows in any of your other tools.

  • Quick setup - Create subscriptions for all relevant 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 from one system to another system. It is an event-driven approach that ensures that notifications get sent at the right time, once an event occurs, and is therefore also known as a reverse API. 

Dixa's webhooks can be for instance used to:

  • update dashboards or key metrics about new events 
  • send notifications about an event to a different tool like Slack, to get other departments notified
  • trigger another automated workflow, once an event has occurred

Setup for webhooks in Dixa

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

1. Go to Settings > Integrations > Webhooks.

2. You will get to your webhooks overview page. 


3. Choose "Add webhook."

4. Fill in the required details:

  • Name: Type a name here, so you can recognise your webhook easily later.
  • 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. You can add basic authorization or a token here.
  • 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.
  • Enable: If you want to enable your webhook subscription straight away, you can toggle it here. If you first want to test the subscription elsewhere, you can also save your webhook in a disabled state. 

5. Choose "Create Webhook" 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.

From your webhooks overview page, you can easily edit your webhook subscription, en- or disable a webhook or delete a webhook. 

Verifying your webhook

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

"t=,v1="

To verify the signature, you can create `signed payload` using the 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 is 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 :  [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 or a token is also supported in the UI:

More details on basic authentication can be read here.

Available event types and payloads

The conversation events that you can subscribe to should give a holistic overview of the full conversation life cycle in Dixa. 

In more detail, you can choose between the following event types:

  • Conversation created: a conversation is created inside Dixa
  • Conversation enqueued: a conversation enters a queue in Dixa
  • Conversation assigned: a conversation gets assigned to an agent
  • Conversation unassigned: a conversation gets unassigned from an agent
  • Conversation closed: a conversation gets closed
  • Conversation note added: an internal note is added to a conversation 
  • Conversation message added: a message is added to the conversation
  • Conversation tag added: a tag is added to the conversation
  • Conversation tag removed: a tag is removed from a conversation
  • Conversation open: a conversation is reopened after closing it
  • Conversation pending: a follow-up is added to a conversation
  • Conversation pending expired: a follow up added to the conversation is expired
  • Conversation transferred: a conversation is transferred to a queue or agent
  • Conversation abandoned: a conversation is closed without an agent being assigned to it
  • Conversation rated: a conversation is rated by the end-user

Each webhook will have a dynamic payload, as not all information is equally important for all events. This means that we adjust the data depending on what event you have subscribed to, which gives you a better overview and makes it easier to retrieve the right information. 

Yet, all payloads include a common conversation type, which looks like the following:

"conversation" : {
    "csid" : 1,
    "channel" : "FACEBOOK_MESSENGER",
    "status" : "OPEN",
    "direction" : "INBOUND",
    "queue" : {
      "id" : "57eaa9ef-b32b-478e-8162-1c38910ac2d1",
      "name" : "myQueue"
    },
    "contact_point" : "Product help page",
    "requester" : {
      "id" : "11f84a2a-a77d-4757-bc8b-ba9df3d2e3f6",
      "name" : "User",
      "email" : "user@dixa.com",
      "phone" : "+4577337109",
      "roles" : ["Enduser"]
    },
    "assignee" : {
      "id" : "73c2d256-bde4-455c-ad5d-de636cdcb06b",
      "name" : "User",
      "email" : "user@dixa.com",
      "phone" : "+4577337109",
      "roles" : ["Admin"]
    }
}

You can see the payload to your subscribed webhooks in Integrations > Webhooks > View Details > View > View payload.


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

Checking the status of your webhooks

Once you have set up and enabled your webhook, you can also follow the deliveries in Dixa. This will make it easy for you to see what is going wrong if a webhook fails and gives you the right tool to find the cause for it.

1. Go to "View Details" of your enabled webhook.

In your Details Overview, you can see the current status of your webhook. A green field (with code) indicates success, a red field (with error code) is a warning for failure. The field is grey if the event has not happened yet.

The status & timestamp corresponds to the last delivery attempt. This will give you an idea if the webhook stopped working. 

2. If you want to get a more detailed view of your subscription for each event type, click on "View" for the particular event. 

Here, you will find information on the last 50 deliveries with response status & timestamp when the delivery was attempted. 

3. You can also view each individual payload to investigate what happened.

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 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 in the top of the Details page of the particular webhook. 
  • Retry logic: A delivery attempt is considered 'failed' if the http response code from the server is not between 200 & 400 (excluded). Such events will be attempted to be delivered every minute for up to a day or at the most 5 times, which means that if the rate of minutes is kept, we will retry for 5 minutes.

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.