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 > Webhooks .

2. You will get to your webhooks overview page.

3. Choose "Add webhook."
4. 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.).
• 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.
• Headers : 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.
• 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.
• Choose "Create Webhook" 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 that they actually came from the Dixa platform by running an HMAC verification on the signed webhook's payload.

To create a 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 Hash-based message authentication code (HMAC) verification on the "signed payload", use the secret key.

For our implementation, we use javax.crypto and a SHA256 algorithm. The secret key is HEX encoded and needs to be decoded if 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]

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 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 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 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 OR a comment concerning the rating is left by the end-user ( NOTE : one webhook is fired for each rating event or rating comment.)
• 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 your subscribed webhooks in Integrations > Webhooks > View > View payload. All payloads include a common structure, which looks like the following:

{
  "event_id": "0be2bd61-7e28-4620-87f0-74952725d960",
  "event_fqn": "CONVERSATION_ASSIGNED",
  "event_version": "1",
  "event_timestamp": "2022-05-10T07:46:44.877Z",
  "organization": {
    "id": "2757a2cf-614e-47ac-8b28-56828bae39bf",
    "name": "Dixa"
  },
  "data": {
    "conversation": {
      "csid": 5000,
      "channel": "CONTACT_FORM",
      "status": "OPEN",
      "direction": "INBOUND",
      "queue": {
        "id": "50a5427e-cfc3-4396-8f4f-a5bce5037d1b",
        "name": "My Queue"
      },
      "contact_point": "demo-webhooks@email.dixa.io",
      "requester": {
        "id": "cab6b2af-5659-4082-98c2-3e056c8d4e3d",
        "name": null,
        "email": "demo-webhooks2@email.dixa.io",
        "phone": null,
        "roles": [
          "Enduser"
        ]
      },
      "assignee": {
        "id": "81f05b32-e002-4af1-9c8d-59e3d243babd",
        "name": "John Doe",
        "email": "jdoe@dixa.com",
        "phone": null,
        "roles": [
          "Admin",
          "Agent",
          "TeamLead"
        ]
      },
      "subject": null,
      "tags": []
    }
  }
}

The event specific information will be inside the data field.

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 ~25 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.
• 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 between 200 & 400 (excluded). 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.