You can send webhook messages to third-party applications based on the results of job executions in your flow.
A webhook task is a callback message between and another application. They are typically delivered using JSON over HTTP and can be interpreted by the receiving application to take action.
NOTE: Your receiving application may require that you whitelist the host and port number or IP address of the platform. Please refer to the documentation for your application. |
Webhook tasks are not included when a flow is copied. They are available to collaborators for review, editing, and execution, when a flow is shared.
Tip: You can export and import the flow, which includes the webhook task definition. See Export Flow. |
You can create a maximum of 50 webhooks per flow.
To send webhooks to a target application, the application must be configured to receive the webhook:
Incoming webhooks must be enabled.
NOTE: Your receiving application may require that you whitelist the host and port number or IP address of the platform. Please refer to the documentation for your application. |
Open your flow in Flow View. From the flow context menu, select Webhooks.
In the right panel, select Create webhook task.
Set the following parameters:
Parameter | Description | ||
---|---|---|---|
Name | User-visible name of the task. | ||
Url | URL where the webhook message is received by the other application. | ||
Trigger event | Select the event that triggers the message. | ||
Trigger object | Select the object or objects that can trigger the message: Any job executed in this flow - Any scheduled or ad-hoc job triggers the message Only specific objects - Select the output or outputs whose success or failure triggers the message | ||
Headers | Insert HTTP content headers as key-value pairs. For example, if your body is in JSON format, you should include the following header:
Please refer to the documentation for your receiving application about the required headers. | ||
Body | (POST , PUT , or PATCH methods only) The body of the request submitted to the receiving application. In the body, you can use the following references: jobId - the internal identifier for the jobGroup that was executed. jobStatus - the status for the job after execution. For more information, see Jobs Page. You can apply metadata references to the flow in the Body text. See below for examples. | ||
Method | Select the HTTP method to use to deliver the message. The appropriate method depends on the receiving application. Most use cases require the POST method. | ||
Secret key | (Optional) A secret key can be used to verify the webhook payload. This secret value must be inserted in this location, and it must be included as part of the code used to process the requests in the receiving application. Insert the secret value here as a string without quotes. For more information on how this secret key is used to generate a signature, see Verify Webhook Signatures below. | ||
Validate SSL certificate | When set to
| ||
Retry on failure | If the returned status code is outside of the 200-299 range, then the webhook is considered to have failed. When this option is enabled, the request is retried. |
In the body of your webhook, you can use the following references:
Reference | Description |
---|---|
$jobId | Internal identifier to the job in the platform. |
$jobStatus | The current status of the webhook job. For more information on job status messages, see Jobs Page. |
You can create a webhook task to run another job on the successful execution of this one.
Tip: Use this method to create conditional sequences of job executions. |
You must acquire the recipe identifier for the next job to execute.
Review the URL for the recipe object. In the example below, the recipe Id value is 4
:
http://www.example.com:3005/flows/1?recipe=4&tab=recipe |
Retain this value for below.
Parameter | Description | |||
---|---|---|---|---|
Name | This name appears in the | |||
Url | Specify the URL as follows, replacing the example values with your own:
| |||
Trigger event | Select Job success . | |||
Trigger object | Select the any option to execute all jobs in the target flow, or you can specify individual jobs to execute. | |||
Headers | Insert the following two headers:
| |||
Body | In the body, insert the recipe Id for the value for
| |||
Method | Select the POST method. |
You can create a webhook task to deliver a text message to a Slack channel of your choice.
Set up your Slack installation to receive webhook messages:
Parameter | Description | |
---|---|---|
Name | This name appears in the | |
Url | Paste the URL that you copied from Slack. | |
Headers | Copy the content headers from the Slack cURL command:
| |
Body |
| |
Method | Select the POST method. |
Depending on the target application, implementing Webhook signature verification may require developer skills. |
Optionally, you can configure the platform to sign the Webhook requests sent for a flow. Signed requests guarantee that the requests are sent from the platform, instead of a third party.
Below, you can review how the signature is created, so that you can configure the receiving application to properly process the signature and its related request.
Webhook requests are signed by inserting the X-Webhook-Signature
header in the request. These signatures are in the following form:
X-Webhook-Signature: t=<timestamp>,sha256=<signature> |
where:
<timestamp>
- Timestamp when the signature was sent. Value is in UNIX time.<signature>
- SHA256 signature. The platform generates this signature using a hash-based message authentication code (HMAC) with SHA-256. More information on these values is available below.
Example:
X-Webhook-Signature: t=1568818215724,sha256=55fa71b2e391cd3ccba8413fb51ad16984a38edb3cccfe81f381c4b8197ee07a |
Depending on the application, you may need to complete one of the following sets of tasks to verify the Webhook signatures:
NOTE: You may need to whitelist the platform in your application. See the application's documentation for details. |
You may be required to create some custom coding for your application. Below, you can review details on how to do so, including a JavaScript example.
The timestamp value (t=<timestamp>
) appears at the beginning of the header value to prevent replay attacks, where an attacker could intercept a valid payload and its signature and re-transmit them.
The Webhook signature includes as part of its hashed value:
Split the X-Webhook-Signature
header:
1568818215724
55fa71b2e391cd3ccba8413fb51ad16984a38edb3cccfe81f381c4b8197ee07a
In the receiving application, you can recompute the signature to verify that the request was sent from the platform.
Suppose the above example is the signature for a POST
request, and the request body is test
. The concatenated value is the following:
1568818215724.test |
You can now compute the HMAC authentication code in your receiving application. In the following JavaScript example, the secret key value is mySecret
:
const crypto = require('crypto'); const message = '1568818215724.test'; // as defined above const hmac = crypto.createHmac('sha256', 'mySecret'); hmac.update(message) const expectedSignature = hmac.digest('hex'); |
The value returned by your code and the value included as the signature in the X-Webhook-Signature
header should be compared: