Webhooks

Important customer engagement events happen in Dixa every day and, for some events, it can be key that you react to them in real-time. With the webhooks feature, you can now subscribe to events in Dixa and have them trigger workflows in any of your tools & systems.

Webhooks represent an event-driven approach which ensures that notifications get sent at the right time, to the right system, once an event occurs, and is therefore also known as a reverse API.

Common webhooks use cases

Some common scenarios where webhooks show their usefulness:

• Updating dashboards or key metrics about new events, e.g. updating your CRM system on customer contact events
• Sending notifications about an event to a different tool, e.g. sending a Slack notification to get other departments notified
• Triggering another automated workflow once an event has occurred, e.g. sending a more detailed survey once the conversation is closed by the agent

How to set up webhooks in Dixa

To set up the webhooks, you need to be a Dixa administrator, as you need to be able to access the settings of your organization in Dixa.

1. Go to Settings > Integrations and click on the Webhooks tab. You will get to your webhooks overview page.

2. Click on "Add webhook." and fill in the required details:

• Name : Provide a descriptive name here, so you can recognize your webhook easier later, e.g. "CRM updates".
• Webhook URL : Specify the URL that the events should be sent to. This could be an API from your internal system or another 3rd party system (e.g. Salesforce, Hubspot, Pipedrive, etc.).
• 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.
• Authorization : Specifying additional headers is optional but might be required by the 3rd party system's API. You can add basic authorization header or a token authorization header.
• 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.
• Click on "Save" to save the new webhook and reveal the option to copy the verification secret for it.

Done!

Changes to the webhook configuration, or removals of webhooks, can be done from the webhooks overview page.

Verifying your webhook

All requests made by webhooks can be verified to have been sent from the Dixa platform by running a Hash-based message authentication code (HMAC) verification on the signed webhook's payload. For that purpose, we include the X-DIXA-SIGNATURE header in the webhook which should contain 2 comma-separated key-value pairs, for example:

"X-DIXA-SIGNATURE" : "t=1689238949803,v1=e217fa759f322839107e2902a16630e6e122418653733ae70f32d1185abcdefg""

The value of t represents the timestamp of the webhook and v1 is the payload signature. To verify this signature, you can concatenate the following values into a string like below:

1. The value of t (as a string)
2. The character .
3. The value of the payload field in the webhook JSON body

Then, using the above concatenated string apply HMAC verification with the SHA256 function using your subscription secret key (you can copy it after creating your subscription). The resulting signature should match the value of the Dixa signature in the field v1. The secret key is HEX encoded and needs to be decoded if used in HMAC. The output signature in v1 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]

Adding a basic authentication header or a token header is also supported in the UI:

More details on basic authentication can be read here.

Available event types and payloads

The events that you can subscribe to provide a holistic overview of the full conversation life cycle in Dixa:

• Conversation created : a conversation is created inside Dixa
• Conversation open : a conversation is reopened (after it was closed)
• Conversation pending : a follow-up is added to a conversation
• Conversation pending expired : a follow-up added to the conversation has expired
• Conversation closed : a conversation gets closed
• Conversation abandoned : a conversation is closed without having an agent assigned
• 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 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 rated : a conversation is rated by the end-user OR a comment concerning the rating is left by the end-user ( NOTE : one webhook is fired for each rating event or rating comment.)
• Conversation transferred to agent : a conversation is transferred to an agent
• Conversation transferred to queue : a conversation is transferred to a queue
• Banned enduser : an end user is banned
• Unbanned enduser : an end user ban is removed
• Banned ip : an IP address is banned
• Unbanned ip : an IP address ban is removed
• Enduser replaced : the end user of a conversation is updated

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, giving you a better overview and making it easier to receive the right information. You can see the payload of the latest webhooks you received in Integrations > Webhooks > View > View payload.

Checking the status of your webhooks

Once you have set up and enabled your webhook, you can follow its operational status in Dixa via the operational details view. This will make it easy for you to diagnoze and debug webhook failures.

1. Click the "View" icon of your enabled webhook.

In your webhook's overview, you can see the current status of your webhook. A green field (with code) indicates success, a red field (with error code) indicates a failure. The field is gray if the event has not been emitted yet. The status & timestamp corresponds to the last delivery attempt. This will give you an idea when the webhook stopped working.

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

Here, you will find information on the last 50 deliveries with response status & timestamps.

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

Auto-disabling webhooks

If your webhook endpoint fails for ~60 times in a row in a 3-hour interval, it will be automatically disabled. This will help ensure that broken endpoints do not affect delivery for working endpoints. To re-enable the webhook, open the Webhooks page in Settings and toggle the Enabled slider.

Implementation considerations

• 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. The event_id field is the UUID identifier of the domain event that originated a given webhook.
• 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 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 in the 2XX or 3XX range. If a delivery attempt fails, we will retry to send it one minute later, and if it fails to deliver 5 times in a row we will not retry again.
• Breaking changes: Both the selection of supported events and the payload returned by each event are subject to evolution. Usually, all changes are incremental & backward compatible. If a breaking change is needed, you will be informed in advance about it.