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.
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
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.
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
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.
To get an X-DIXA-SIGNATURE header, it should contain 2 comma-separated key-value pairs:
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
- 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.
- Conversation closed: Receive a webhook every time a conversation gets closed.
Each webhook will have the following payload:
“requester_name”: “Requester Name”,
“assignee_name”: “Assignee Name”,
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.
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.
None at the moment.