Skip to main content

Create Flow Webhook Task

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 Designer Cloud 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.

  • A webhook task is defined at the flow level, although an individual webhook task can be restricted to specific outputs. It is shared between ad-hoc and scheduled executions.

For more information on how to orchestrate execution of your flows, see Overview of Operationalization.

Limitations

  • Custom security certificates cannot be used.

  • HTTP-based requests have a 30-second timeout limit.

  • 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.

  • You can create a maximum of 50 webhooks per flow.

Prerequisites

Requirements for receiving application

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.

  • You must acquire the URL of the endpoint to which to send the webhook request.

  • You must acquire any HTTP headers that must be inserted with each webhook request.

  • If the request must be signed, additional configuration is required. Details are below.

Steps

  1. Open your flow in Flow View. From the flow context menu, select Webhooks.

  2. In the right panel, select Create webhook task.

  3. 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:

    key: Content-Type
value: application/json

    Note

    You may be required to submit an authentication token as the value for the Authorization key.

    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 Job History 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 true, HTTPS (SSL) communications are verified to be using a valid certificate before transmission.

    Note

    If you must send a request to an endpoint that has an expired/invalid certificate, you must disable SSL verification.

    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.

  4. To test the connection, click Test. A success message is displayed.

  5. To add the webhook task to the flow, click Create.

  6. When the job is executed:

    1. Depending on the outcome, the webhook task is executed through the other application.

    2. The webhook is listed in the Job Details page.

Flow metadata references in body

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 Job History Page.

Examples

Run another job

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.

Prerequisites

You must acquire the recipe identifier for the next job to execute.

  1. Open the flow containing the next recipe.

  2. In Flow View, click the recipe whose outputs you wish to generate.

  3. 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

  4. Retain this value for below.

Define the flow webhook task

Parameter

Description

Name

This name appears in the Cloud Portal only.

Url

Specify the URL as follows, replacing the example values with your own:

http://www.example.com:3005/v4/jobGroups/

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:

key: Content-Type
value: application/json
key: Authorization
value: Bearer <paste your access token here>

Note

The token value must be preceded by the string: Bearer.

Body

In the body, insert the recipe Id for the value for wrangledDataset, which is the internal platform term for recipe:

{
  "wrangledDataset": {
    "id": 4
  }
}

Method

Select the POST method.

Verify

  1. Run the job for which the webhook was created.

  2. When the job successfully completes, open the flow containing the other job to execute.

  3. When you select the target recipe, a new job should be queued, in-progress, or completed.

Slack channel message

You can create a webhook task to deliver a text message to a Slack channel of your choice.

Prerequisites

Set up your Slack installation to receive webhook messages:

  1. If needed, create a Slack channel to receive your messages.

  2. Create an app.

  3. Activate incoming webhook messages for your app.

  4. Specify the channel to receive your incoming webhook messages.

  5. Copy the URL for the incoming webhook from the cURL statement.

Define the flow webhook task

Parameter

Description

Name

This name appears in the Cloud Portal only.

Url

Paste the URL that you copied from Slack.

Headers

Copy the content headers from the Slack cURL command:

key: Content-Type
value: application/json

Body

{"text":"Job $jobId has completed. Status: $jobStatus."}

Method

Select the POST method.

Verify

  1. Click Test to validate that this webhook task will work.

  2. Run a job:

    1. Check the Slack channel for a message.

    2. Check the Webhook tab in the Job Details page.

Verify Webhook Signatures

Warning

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 Signature Header

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

Check Application Tools

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.

Process Signed Requests

Timestamp

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.

  • To avoid such attacks, a timestamp is included in the signature header and is also embedded as part of the signed payload.

  • Since the timestamp is part of the signed payload, an attacker cannot change the timestamp value without invalidating the signature.

    • If the signature is valid but the timestamp is too old, you can then choose to reject the request.

    • For example, if you receive a request with a timestamp that corresponds to a date from one hour ago, you should probably reject the request.

  • For more information on replay attacks, see https://en.wikipedia.org/wiki/Replay_attack.

Signature

The Webhook signature includes as part of its hashed value:

  • The secret key (entered above)

  • The timestamp value

  • Request data:

    • (POST/PUT/PATCH) - the body of the request

    • (GET/DELETE) - URL of the request

Step 1 - Extract the timestamp and signatures

Split the X-Webhook-Signature header:

  1. Split values using the , character as a separator.

  2. Split each of the parts using the = character.

  3. Extract the values for the timestamp and signature. From the above example:

    1. timestamp: 1568818215724

    2. signature: 55fa71b2e391cd3ccba8413fb51ad16984a38edb3cccfe81f381c4b8197ee07a

Step 2 - Create the expected signature

In the receiving application, you can recompute the signature to verify that the request was sent from the platform.

  1. Concatenate the timestamp, the dot character . and the request body (POST/PUT/PATCH methods) or the url (GET/DELETE methods).

  2. 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

  3. 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');

Step 3 - Compare the signatures

The value returned by your code and the value included as the signature in the X-Webhook-Signature header should be compared:

  • If the values do not match, reject the request.

  • If the values do match, compute the difference between the current timestamp and the timestamp in the header. If the difference is outside of your permitted limit, reject the request.

  • Otherwise, process the request normally in your application.

In this section: