What are Webhooks and how do I get notified when a Workflow is completed?

Webhooks allow you to set up your own integrations to Malcolm! Workflow. By subscribing to the Workflow Completed event you will receive a HTTP POST Payload containing information about the completed Session. You could use this information to keep local records of when your Workflows are completed as well as receiving meta data like the start and completed times.

For security and data privacy reasons we do not include the submitted Values in the payload. There are numerous ways the Values can be retrieved and matched up to the Session. The simplest way is to use the MyMalcolm Control Panel. Here you can view or export the Values. Alternatively, if you're on our Enterprise Plan, you can request an API Key and programmatically fetch the Values using our friendly REST API.

Configuration

Webhooks are are configured in "Workflow > Configure > Webhooks" section of MyMalcolm.

The only requirement when adding or editing an existing Webhook is the URL. This is the URL Malcolm! will send the HTTP POST Payload to. The URL should be a secure URL (that means it starts with https://) and publicly accessible - i.e. not behind a firewall or on a local machine.

Screenshot 2020-04-03 at 10.46.22.png

There are conditional controls available too. If you have a condition configured the HTTP POST Payload will only be sent if the conditions at the end of the Workflow are satisfied.

Screenshot 2020-04-03 at 10.46.43.png

Payload

The Payload is a simple HTTP POST with JSON Body.

The Payload will contain the following special Headers.

Header Description
X-Instance-Id The ID of the Instance. E.g. "xxxxxxxxxx"

The Body will contain the following attributes.

Attribute Description
id The ID of the Workflow Session. E.g. "xxxxxxxxxx"
label A descriptive label, which will include the name of the person who completed the Workflow if your Workflow contains name attributes. E.g. "Completed by Malcolm!"
locale The locale used during the Workflow. E.g. "en-GB"
started-at The localised date and time the Session was started. E.g. "2020-04-01 12:00:00"
completed-at The localised date and time the Session was completed. E.g. "2020-04-01 12:00:00"
workflow.id The ID of the Workflow. E.g. "xxxxxxxxxx"
workflow.name The name of the Workflow. E.g. "Open Support Ticket"
workflow.published-at The localised date and time the Workflow was published. E.g. "2020-04-01 09:00:00"
workflow.version The name of the Workflow version. E.g. "Version 1"

Example Payload

POST /workflow-completed HTTP/1.1
Host: webhooks.my-domain.com
Content-Type: application/json
X-Instance-Id: xxxxxxxxxx
{
  "id": "xxxxxxxxxx",
  "label": "Completed by Malcolm!",
  "locale": "en-GB",
  "started-at": "2020-04-01 12:00:00",
  "completed-at": "2020-04-01 12:05:00",
  "workflow": {
    "id": "xxxxxxxxxx",
    "name": "Open Support Ticket",
    "published-at": "2020-04-01 09:00:00",
    "version": "Version 1"
  }
}

API

For Enterprise customers a further HTTP GET Payload can be used to fetch the associated Values.

Endpoint
GET /sessions/xxxxxxxxxx/values
Header Description
Host api.malcolm.solutions/1.0/workflow-api
Accept application/json
Authorization A Bearer string composed by concatenating "api-key:" and your API key and then Base 64-encoding the result. E.g. "Bearer xxxxxxxxxx"
X-Instance-Id The ID of the Instance. E.g. "xxxxxxxxxx"

Example Response

{
  "data": [
    {
      "attributes": {
        "is-valid": true,
        "value": "Malcolm!"
      },
      "id": "xxxxxxxxxx",
      "links": {
        "self": "/values/xxxxxxxxxx"
      },
      "meta": {
        "field": {
          "id": "xxxxxxxxxx",
          "name": "Name",
          "required": true,
          "type": "Name"
        }
      },
      "relationships": {
        "field": {
          "links": {
            "related": "/values/xxxxxxxxxx/field",
            "self": "/values/xxxxxxxxxx/relationships/field"
          }
        }
      },
      "type": "values"
    },
    ...
  ],
  "links": {
    "first": "/sessions/xxxxxxxxxx/values?page=1",
    "last": "/sessions/xxxxxxxxxx/values?page=1",
    "self": "/sessions/xxxxxxxxxx/values?page=1"
  },
  "meta": {
    "pagination": {
      "total": 1,
      "per-page": 1,
      "current-page": 1,
      "page-count": 1,
      "from": 1,
      "to": 1
    }
  }
}

For further help or information on our Enterprise Plan please contact the Support Team.

Did this help you?
20% found this useful
Thank you for submitting your feedback.

Upgrade your content

Want to give your users a graphical run-down of how your products or services work? Malcolm! Agency Services can help

Learn more

Hey there!

Malcolm! is brought to you by a passionate and dedicated team - we love all things customer support related! Find out more about us here

Find out more