Running a workflow from another application with the API webhook trigger

The API webhook trigger will start a workflow when you send an HTTP POST to Trelica. This could be from another application (e.g. Jira) or from some custom code.

Input values

You can add input fields to the webhook trigger.

Each field has a name and an ID. The ID maps to a path in the JSON. e.g. the ID person.email would be valid for this JSON fragment:

{
    "person": {
        "email": "test.person@example.org"
    }
} 

When you add fields Trelica will show you a sample of some JSON that would match the fields you've configured.

Handling more complicated input payloads

You might find that you can't easily express the location of the data you want in the JSON using a simple 'dot' notation. For example, the webhook payload might contain an array. When you add or edit a field, Trelica lets you enter JSON paths using a powerful query language called JMESPath.

Workflow context

Each workflow has a context. Often this is implicit in the workflow trigger, e.g. 'Person leaves' relates to a Trelica person.

Webhooks, like on-demand workflow triggers, can work for any context. Depending on the context you pick you will need to specify a field in the JSON that gets sent to Trelica that identifies the context.

e.g. for a person that would be the email address, so you would need to specify a path to the value in the JSON that contains the email address.

Testing a webhook

A special test mode helps you test webhooks.

This shows you what has been posted, whether it is valid, and how the data has been mapped to the different input fields.

Enabling a webhook

When you are happy with your workflow you can enable it.

Security

Each Trelica webhook is assigned a unique URL which is randomly generated and hard to guess.

URLs are generally not encrypted in transit however, and often get written to logs, so we recommend using additional measures to ensure that the application posting to the Trelica webhook is the one you expect.

Send a Secret in a header

A simple way to do this is to include an HTTP header with a shared-secret (some text that is known only to Trelica and the sending application). You can add the shared-secret to Trelica so that it can check it is the same when requests are received.

Many applications support adding headers when calling webhooks, e.g. Jira.

You can give the header any name and value that you want.

curl -X POST 'https://app.trelica.com/FlowApi/webhooks/xxxxxxxxxx/yyyyyyyyyyyy' \
  -H 'Content-Type: application/json' \
  -H 'x-secret: a-shared-secret' \
  -d '{"recipient": {"email": "jane.doe@example.org"},"message": "Example"}'

Send a Signature in a header

A more sophisticated way to is to compute a hash for the data being sent. This uses a key that is known only to the application sending the data and Trelica, so Trelica can ensure that the data being sent was generated by the expected application.

Hashes can be computed from different things, and some applications implement custom strategies, e.g. sending a header with the time the hash was computed and including this in the hash, allowing Trelica to verify that the data was sent recently, and is not being replayed at a later date.

Trelica supports basic SHA-256 hashing of the HTTP POST body, and application specific strategies where appropriate.

Currently BambooHR is the only application specific strategy supported.

Here's an example using node.js of sending a signed payload using a basic SHA-256 hash:

import * as crypto from 'crypto'
import fetch from 'node-fetch'

// test URL
const href = "https://app.trelica.com/FlowApi/webhook-test/xxxx/yyyy";

// signature private key
const signatureKey = "0123456789ABCDEF0123456789ABCDEF01234567";

// POST body
const body = {
    recipient: { email: "jane.doe@example.org" },
    message: "Running this workflow..."
};

// Make the request
const request = {
    method: "POST",
    body: JSON.stringify(body,null,2),
    headers: {
        "Accept": "application/json",
        "Content-Type": "application/json"
    }
};

const hexKey = Buffer.from(signatureKey, "hex");
request.headers["x-hmac"] = crypto.createHmac("sha256", hexKey)
    .update(request.body).digest("hex");

const response = await fetch(href, request);
const data = await response.text(); 
console.log(response.status + ": " + data);

An HTTP 401 will be returned if the wrong signature is sent with the POST.

Responses

HTTP 201

{
  "workflowRunId": "xxxxxxxxxxxxxxx",
  "workflowRunLink": "https://app.trelica.com/Admin/FlowItem/xxxxxxxxxxxxxxx",
  "success": true
}

HTTP 400

Bad request - a context parameter was not found or processed correctly, or a field was of the wrong type.

Example response:

{
  "errors": {
    "recipient.email": [
      "error_missing_mandatory_field - No value found for context: recipient.email"
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "extensions": {
    "traceId": "00-423a44a13306d0a1cc3983582639fb24-6153c2da95489a1f-01"
  }
}

HTTP 401

The signature or shared secret were invalid. 

HTTP 404

The URL was not found - check the workflow has been enabled.