Outbound webhooks

Important conversation events happen in Dixa every day, and it can be key that you react to them in real time. With the outbound 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 once an event occurs, notifications get sent at the right time to the right system.

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 an agent

How to set up webhooks in Dixa

To set up an outbound webhook, 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. Here you will find the Outbound webhooks table. Click on the button Add outbound webhook to navigate to the creation page.

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

• Name : Provide a descriptive name here, so you can identify your webhook 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 third-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 third-party system's API. You can add a basic authorization header or a token authorization header.
• Events to subscribe to : Select the events you are interested in getting notified about. You can read about the available event types and payloads further below.
• Filters : Filters allow a more grained selection of events to listen to. Only filtered events will be sent out, it can target conversation channel, queue...

3. Click 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 two 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 this value from your webhook's page 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 diagnose 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.

Automating the monitoring of your webhook deliveries

You can automate the monitoring of the delivery status of your webhooks using the Dixa API. The Webhook Subscription Last Delivery Statuses endpoint will give you information about the latest delivery statuses for each event of your webhook subscription. You can set up an automation to periodically query this endpoint and alert you if any error statuses are returned by your server, so you can quickly react to any issues with your subscription, e.g.: a cron-job that queries the endpoint every 30 seconds, or a more appropriate interval that suits your needs, within the overall API rate limits.

For a more detailed overview of the delivery status for a particular event you have subscribed to, you can use the Webhook Subscription Event Logs endpoint, which will additionally provide you with the payload of each event coupled with the delivery status. This can be very useful for troubleshooting any issues.

Delivery Errors and Retry Strategy

Webhook delivery can fail for different reasons. We handle delivery failures differently, according to each error response range that we receive from your server:

• 4XX HTTP error - A webhook delivery with this type of error response will not be retried, as it most likely requires an intervention on your part to make the delivery successful.
• 5XX HTTP and network errors (e.g. timeouts) - We will attempt to redeliver the webhook up to 3 times with an interval of 1 minute between retries. After the maximum number of retries is exhausted, we will drop the message.

If webhook deliveries to your server fail for ~15 consecutive times, we will stop retrying failed deliveries until we receive a successful response(e.g. HTTP 200). This will help ensure that broken endpoints do not affect delivery for working endpoints. It's important that you frequently monitor the delivery status of your webhooks to avoid missing events.

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.

• 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.
• Supported protocols: Our Webhooks HTTP client supports TLSv1.3, TLSv1.2, TLSv1.1 and TLSv1. Make sure your server has support for at least one of these versions when setting up your webhook notifications.