Webhooks

Use Webhooks to send information to external systems when a new event has occurred in CXM.

Currently the following events can trigger a webhook:

Configuring webhooks

Navigate to Settings > System > Webhooks to see a list of the webhooks configured in the system.

Webhook list

This table is searchable, and shows the webhook Name, whether its Status is enabled or disabled, the number of Triggers for the webhook, and links to perform Actions for each webhook. We will explain this in more detail in the following sections.

In order to create a new webhook, click on New Webhook and enter the values for the fields.

Webhook creation form

  • The Name is used to identify the webhook.

  • The target URL is the location where the data will be sent to. Needs to be a valid URL using HTTPS.

  • The Secret will need to be known by the external system in order to verify the request, this should not be shared anywhere else.

  • The Enabled switch can be used to enable or disable sending of webhook requests. Requests will not be queued up whilst the webhook is disabled.

  • The webhook will send requests whenever any of the selected Event triggers occur.

In order to edit an existing webhook, click on its name in the list and, under the General tab, edit the fields as needed.
Click on Delete to permanently remove the webhook from the system.

Webhook edit form

Under the Event Triggers tab, there is a list of the triggers for the webhook.

Webhook event triggers list

This list shows the name of the Trigger and its Payload version, and contains links to perform Actions for each trigger.

Existing event triggers can be removed by clicking Delete, and new event triggers can be added by clicking Add Event Triggers.

Webhook Event Triggers

When any of the events described in this section occur in CXM, the webhooks configured to do so, will be triggered. This means that a HTTP request will be sent to the target URL specified for the webhook, including specific headers and the corresponding data payload, as described below.

HTTP Headers

Every webhook request from CXM contains the following headers.

  • User-Agent:
    Standard header with the value "Jadu CXM Webhook". It allows the external system to identify CXM as the requesting software agent. [Read more]
  • Content-Type:
    Standard header with the value "application/json". It tells the external system that the payload content is JSON. [Read more]
  • X-Hook-Delivery:
    Custom header with the value "{uuid}", where {uuid} is the universally unique identifier for each webhook delivery, which is displayed in the Webhook Log.
  • X-Hook-Event:
    Custom header with the value "{type}", where {type} is the type of the main entity the webhook relates to (e.g. "user" or "case").
  • X-Hook-Signature:
    Custom header with the value "sha1={hash}", where {hash} is a keyed hash of the payload. It allows the external system to confirm that the request actually comes from CXM.
    The hash is generated using the HMAC method, SHA-1 algorithm, and the webhook secret as the encryption key. For example, if the payload is {"data": "The webhook data..."} and the webhook secret is s3cr3t, the resulting value for the header will be "sha1=db0b02a84d83e82526d1d14cdd42652cc217536e".

Data payload

The data for the webhook event trigger is sent as the request body, in JSON format. All webhook requests will be a JSON object, including always the keys action (with the name of the event) and version (with the version of the payload), and then one or more keys for the entities related to the event. For example, for the Case created event, CXM will send something like:

 {
     "version": 1,
     "action": "case_created",
     "case": {...},
     "created_by": {...}
 }

It is guaranteed that a given webhook will always send the data payload with the same JSON structure for a given event in a given version. However, following JSON specification, the order of the entries might vary.

Types of events

Attachment added

Triggered when a new file is added to a case, either attached to a timeline message, or uploaded directly from the Files tab.

Note: for security reasons, the download_url included in the webhook payload is only available for a short period of time, specified in the download_url_expiry date.
After that time, the Get Attachment by Identifier Service API endpoint can be used to fetch the attachment again, which will include a fresh download URL. The Service API endpoint URL is built using the case reference and the attachment identifier from the webhook payload, like /case/{reference}/attachment/{identifier}.

Example payload:
{
    "action": "attachment_added",
    "version": 1,
    "added_by": {
        "email": "john.smith@test.com",
        "name": "John Smith",
        "reference": "123"
    },
    "attachment": {
        "description": "The description of the attachment.",
        "file_name": "some_picture.jpeg",
        "mime_type": "image/jpeg",
        "size": 1024,
        "identifier": "555",
        "download_url": "http://attachment.test",
        "download_url_expiry": "2020-02-02T14:32:25+00:00"
    },
    "case": {
        "type": {
            "slug": "my_case_type",
            "title": "My case type"
        },
        "reference": "ABC000123"
    }
}

User created

Triggered whenever a user record is created, for example when creating it manually from the User Administration tab, or when a user signs up using public registration.

Example payload:
{
    "version": 1,
    "action": "create",
    "user": {
        "created_at": "2019-01-01T01:00:00+00:00",
        "email": "john.smith@test.com",
        "email_verified": true,
        "enabled": true,
        "forename": "John",
        "group": {
            "slug": "the-user-group",
            "title": "The User Group"
        },
        "id": 123,
        "incomplete": false,
        "name": "John Smith",
        "photo": "http:\/\/user-photo.test",
        "privilege_level": {
            "slug": "the-user-role",
            "title": "The User Role"
        },
        "reference": "r3f3r3nc3",
        "surname": "Smith",
        "timezone": "Europe\/London",
        "type": {
            "slug": "the-user-type",
            "title": "The User Type"
        },
        "updated_at": "2019-02-02T02:00:00+00:00"
    }
}

User updated

Triggered when the details of a user are changed, either by someone else on the User Administration tab, or by themselves using My Details form.

Example payload:
{
    "version": 1,
    "action": "update",
    "user": {
        "created_at": "2019-01-01T01:00:00+00:00",
        "email": "john.smith@test.com",
        "email_verified": true,
        "enabled": true,
        "forename": "John",
        "group": {
            "slug": "the-user-group",
            "title": "The User Group"
        },
        "id": 123,
        "incomplete": false,
        "name": "John Smith",
        "photo": "http:\/\/user-photo.test",
        "privilege_level": {
            "slug": "the-user-role",
            "title": "The User Role"
        },
        "reference": "r3f3r3nc3",
        "surname": "Smith",
        "timezone": "Europe\/London",
        "type": {
            "slug": "the-user-type",
            "title": "The User Type"
        },
        "updated_at": "2019-02-02T02:00:00+00:00"
    }
}

Case created

Triggered when a new case is created, directly using a form inside CXM, or from an external system through a Service API.

Note: currently cases created through the Case Import functionality do not trigger this event.

Example payload:
{
    "action": "case_created",
    "version": 1,
    "case": {
        "address_relationships": [
            {
                "address": {
                    "administrative_area": "addr_admin_area",
                    "custom": false,
                    "easting": 5000,
                    "external_reference": "ADD123_EXTERNAL",
                    "locality": "addr_locality",
                    "northing": 6000,
                    "paon": "addr_paon",
                    "post_code": "LE191RJ",
                    "post_town": "Leicester (post town)",
                    "reference": "ADD123",
                    "saon": "addr_saon",
                    "street": "Leicester Street",
                    "summary": "Addr_saon, Addr_paon, Leicester Street, Addr_locality, Leicester (town), Leicester (post Town), LE191RJ",
                    "town": "Leicester (town)",
                    "type": "property",
                    "uprn": "addr_uprn-123",
                    "usrn": "addr_usrn-123"
                }
            }
        ],
        "status": {
            "slug": "start",
            "title": "Start",
            "type": "initial"
        },
        "type": {
            "service": {
                "slug": "my_case_type_service",
                "title": "My case type service"
            },
            "slug": "my_case_type",
            "title": "My case type"
        },
        "values": {
            "checkbox_field_a": {
                "type": "checkbox",
                "name": "checkbox_field_a",
                "redacted": false,
                "value": true
            },
            "checkbox_field_b": {
                "type": "checkbox",
                "name": "checkbox_field_b",
                "redacted": false,
                "value": false
            },
            "choices_field_a": {
                "type": "choice",
                "name": "choices_field_a",
                "redacted": false,
                "value": [
                    "choice_b",
                    "choice_a"
                ]
            },
            "choice_field_a": {
                "type": "choice",
                "name": "choice_field_a",
                "redacted": false,
                "value": "choice_b"
            },
            "date_time_field_a": {
                "type": "datetime",
                "name": "date_time_field_a",
                "redacted": false,
                "value": "2019-10-20T14:31:32+00:00"
            },
            "date_field_a": {
                "type": "date",
                "name": "date_field_a",
                "redacted": false,
                "value": "2019-10-09"
            },
            "encrypted_textarea_field_a": {
                "type": "textarea",
                "name": "encrypted_textarea_field_a",
                "redacted": false,
                "value": "my encrypted textarea value"
            },
            "encrypted_text_field_a": {
                "type": "text",
                "name": "encrypted_text_field_a",
                "redacted": false,
                "value": "my encrypted textarea value"
            },
            "textarea_field_a": {
                "type": "textarea",
                "name": "textarea_field_a",
                "redacted": false,
                "value": "my textarea value"
            },
            "text_field_a": {
                "type": "text",
                "name": "text_field_a",
                "redacted": false,
                "value": "my text value"
            },
            "url_field_a": {
                "type": "url",
                "name": "url_field_a",
                "redacted": false,
                "value": "my url value"
            },
            "text_field_redacted": {
                "type": "text",
                "name": "text_field_redacted",
                "redacted": true,
                "value": null
            }
        },
        "created_at": "2019-10-09T13:10:10+00:00",
        "organisation_relationships": [
            {
                "organisation": {
                    "address": {
                        "administrative_area": "org_admin_area",
                        "custom": false,
                        "easting": 5000,
                        "external_reference": "ORG123_EXTERNAL",
                        "locality": "org_locality",
                        "northing": 6000,
                        "paon": "org_paon",
                        "post_code": "LE191RJ",
                        "post_town": "Leicester (post town)",
                        "reference": "ADD123",
                        "saon": "org_saon",
                        "street": "Leicester Street",
                        "summary": "Org_saon, Org_paon, Leicester Street, Org_locality, Leicester (town), Leicester (post Town), LE191RJ",
                        "town": "Leicester (town)",
                        "type": "property",
                        "uprn": "org_uprn-123",
                        "usrn": "org_usrn-123"
                    },
                    "name": "Acme Inc",
                    "reference": "ORG123"
                }
            }
        ],
        "person_relationships": [
            {
                "person": {
                    "addresses": [
                        {
                            "administrative_area": "addr_admin_area",
                            "custom": false,
                            "easting": 5000,
                            "external_reference": "ADD123_EXTERNAL",
                            "locality": "addr_locality",
                            "northing": 6000,
                            "paon": "addr_paon",
                            "post_code": "LE191RJ",
                            "post_town": "Leicester (post town)",
                            "reference": "ADD123",
                            "saon": "addr_saon",
                            "street": "Leicester Street",
                            "summary": "Addr_saon, Addr_paon, Leicester Street, Addr_locality, Leicester (town), Leicester (post Town), LE191RJ",
                            "town": "Leicester (town)",
                            "type": "property",
                            "uprn": "addr_uprn-123",
                            "usrn": "addr_usrn-123"
                        },
                        {
                            "administrative_area": "addr_admin_area",
                            "custom": false,
                            "easting": 5000,
                            "external_reference": "ADD123_EXTERNAL",
                            "locality": "addr_locality",
                            "northing": 6000,
                            "paon": "addr_paon",
                            "post_code": "LE191RJ",
                            "post_town": "Leicester (post town)",
                            "reference": "ADD123-2",
                            "saon": "addr_saon",
                            "street": "Leicester Street",
                            "summary": "Addr_saon, Addr_paon, Leicester Street, Addr_locality, Leicester (town), Leicester (post Town), LE191RJ",
                            "town": "Leicester (town)",
                            "type": "property",
                            "uprn": "addr_uprn-123",
                            "usrn": "addr_usrn-123"
                        }
                    ],
                    "email": "bob@test.com",
                    "name": "Bob Bartholomew Leopold Tester",
                    "primary_address": {
                        "administrative_area": "addr_admin_area",
                        "custom": false,
                        "easting": 5000,
                        "external_reference": "ADD123_EXTERNAL",
                        "locality": "addr_locality",
                        "northing": 6000,
                        "paon": "addr_paon",
                        "post_code": "LE191RJ",
                        "post_town": "Leicester (post town)",
                        "reference": "ADD123",
                        "saon": "addr_saon",
                        "street": "Leicester Street",
                        "summary": "Addr_saon, Addr_paon, Leicester Street, Addr_locality, Leicester (town), Leicester (post Town), LE191RJ",
                        "town": "Leicester (town)",
                        "type": "property",
                        "uprn": "addr_uprn-123",
                        "usrn": "addr_usrn-123"
                    },
                    "reference": "PER123"
                }
            }
        ],
        "reference": "CASE12345678",
        "updated_at": "2019-10-09T19:10:11+00:00"
    },
    "created_by": {
        "email": "john.bobson@cxmtest.com",
        "group": {
            "slug": "my_user_group",
            "title": "My user group"
        },
        "name": "John Bobson",
        "person": {
            "addresses": [
                {
                    "administrative_area": "addr_admin_area",
                    "custom": false,
                    "easting": 5000,
                    "external_reference": "ADD123_EXTERNAL",
                    "locality": "addr_locality",
                    "northing": 6000,
                    "paon": "addr_paon",
                    "post_code": "LE191RJ",
                    "post_town": "Leicester (post town)",
                    "reference": "CREATING_USER_ADDR_123",
                    "saon": "addr_saon",
                    "street": "Leicester Street",
                    "summary": "Addr_saon, Addr_paon, Leicester Street, Addr_locality, Leicester (town), Leicester (post Town), LE191RJ",
                    "town": "Leicester (town)",
                    "type": "property",
                    "uprn": "addr_uprn-123",
                    "usrn": "addr_usrn-123"
                },
                {
                    "administrative_area": "addr_admin_area",
                    "custom": false,
                    "easting": 5000,
                    "external_reference": "ADD123_EXTERNAL",
                    "locality": "addr_locality",
                    "northing": 6000,
                    "paon": "addr_paon",
                    "post_code": "LE191RJ",
                    "post_town": "Leicester (post town)",
                    "reference": "CREATING_USER_ADDR_123-2",
                    "saon": "addr_saon",
                    "street": "Leicester Street",
                    "summary": "Addr_saon, Addr_paon, Leicester Street, Addr_locality, Leicester (town), Leicester (post Town), LE191RJ",
                    "town": "Leicester (town)",
                    "type": "property",
                    "uprn": "addr_uprn-123",
                    "usrn": "addr_usrn-123"
                }
            ],
            "email": "bob@test.com",
            "name": "Bob Bartholomew Leopold Tester",
            "primary_address": {
                "administrative_area": "addr_admin_area",
                "custom": false,
                "easting": 5000,
                "external_reference": "ADD123_EXTERNAL",
                "locality": "addr_locality",
                "northing": 6000,
                "paon": "addr_paon",
                "post_code": "LE191RJ",
                "post_town": "Leicester (post town)",
                "reference": "CREATING_USER_ADDR_123",
                "saon": "addr_saon",
                "street": "Leicester Street",
                "summary": "Addr_saon, Addr_paon, Leicester Street, Addr_locality, Leicester (town), Leicester (post Town), LE191RJ",
                "town": "Leicester (town)",
                "type": "property",
                "uprn": "addr_uprn-123",
                "usrn": "addr_usrn-123"
            },
            "reference": "PER123"
        },
        "privilege_level": {
            "slug": "my_privilege_level",
            "title": "My privilege level"
        },
        "reference": "USR123",
        "type": {
            "slug": "my_user_type",
            "title": "My user type"
        }
    }
}

Case transitioned

Triggered when a new case is transitioned, directly from inside CXM, or from an external system through a Service API. If the transition has a case form attached, the payload will contain the new values set with this form.

Note: The transitioned_by property will be null if the case was transitioned by a rule action.

Example payload:
{
    "action": "case_transitioned",
    "version": 1,
    "case": {
        "address_relationships": [],
        "status": {
            "slug": "in_progress",
            "title": "In progress",
            "type": "normal"
        },
        "type": {
            "service": {
                "slug": "my_case_type_service",
                "title": "My case type service"
            },
            "slug": "my_case_type",
            "title": "My case type"
        },
        "values": {
            "choice_field_a": {
                "type": "choice",
                "name": "choice_field_a",
                "redacted": false,
                "value": "choice_b"
            },
            "text_field_a": {
                "type": "text",
                "name": "text_field_a",
                "redacted": false,
                "value": "my text value"
            }
        },
        "created_at": "2019-10-09T13:10:10+00:00",
        "organisation_relationships": [],
        "person_relationships": [],
        "reference": "CASE12345678",
        "updated_at": "2019-10-09T19:10:11+00:00"
    },
    "transition": {
        "slug": "start",
        "title": "Start"
    },
    "transitioned_by": {
        "email": "john.bobson@cxmtest.com",
        "name": "John Bobson",
        "reference": "USR123"
    },
    "previous_status": {
        "slug": "open",
        "title": "Open",
        "type": "initial"
    },
    "new_status": {
        "slug": "in_progress",
        "title": "In progress",
        "type": "normal"
    }
}

Webhook Log

For each webhook, under the Log tab, there is a list of all the past requests for that webhook. Exploring this list may be useful to identify issues in case the webhook is not configured correctly, or external system is failing to process the webhook.

When an event occurs in CXM that triggers a webhook, one webhook delivery is generated with pending status. Then CXM tries to make a request with the webhook data to the external system, and if it receives a successful response, it sets the status of the delivery as success. If the external system replies with an error, CXM will retry the request up to 7 more times over a period of approximately 1.5 hours, after which the delivery status will be set as error. All requests for the same delivery will have the same delivery ID and data payload.

Webhook log

  • The Created column shows the date when the webhook delivery was created, which is just after the event occurred in CXM.
  • The Event type column shows the type of event that triggered the webhook.
  • The Status column shows the current status of the delivery (which can be pending, success or error).
  • The Delivery ID column contains the universally unique identifier for the delivery, which is sent in the headers of the request.
  • The Entity column provides a link to the main entity related to the webhook delivery (e.g. a link to the case that was created or to the user record that was updated).
  • Clicking on the link in the Details column opens up a panel with extra information about the delivery.

Webhook log details panel for a successful delivery

On the details panel, the Info section at the top contains the same details displayed on the list plus the Last requested date, which is the moment when CXM last tried to make the delivery, and the number of Total attempts tried.

The Last reponse section contains details of the last response received from the external system the last time CXM attempted to send the webhook request. This is just standard HTTP information such as the Response status and the Headers.

When the delivery is in pending or error status, the details panel also includes a Request section at the bottom, which contains the Body of the last request made by CXM. This information is erased once the delivery is successful.

Webhook log details panel for a failed delivery

results matching ""

    No results matching ""