Webhook configuration

In this section, you will learn how to set up webhooks in Taskurai.

Webhooks can defined in the Taskurai configuration (YAML) and are deployed and managed using the Taskurai CLI.

Webhooks deployment configuration

A webhook is deployed using a configuration section in the solution yaml.

Reference webhook configuration

This is a reference webhook configuration sample:

• WebhookUploadSAPSucceeded:
  • Send webhook for each task with the command UploadDailySalesSAP, running in isolation mode with isolation key 46e49c2c-cdd4-48e8-9106-f32c0a77a64e, that has completed with the status Succeeded, including a condensed payload, excluding sensitive data. The global secret webhooksecret is used for the calculation of the HMAC key.

...
secrets:
  - webhooksecret
...
webhooks:
  WebhookUploadSAPSucceeded:
    description: Catch all succeeded tasks for the command UploadDailySalesSAP
    url: https://webhook.site/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
    events:
    - UploadDailySalesSAP.Succeeded
    isolationMode: true
    isolationKey: 46e49c2c-cdd4-48e8-9106-f32c0a77a64e
    includeFullPayload: false
    includeSensitive: false
    secret:
      name: webhooksecret
      secretReference: webhooksecret
...      

Webhook configuration

Property	Type	Required	Additional requirements	Description
name	string	No	1-20 alphanumeric characters and hyphens	Override webhook name (default: webhook key)
description	string	No		Webhook description
url	string	Yes		Webhook URL (must be HTTPS and have a valid certificate)
secret	Secret	No		Webhook secret used to generate HMAC signature (if none is provided, a secret is generated)
events	List of events	No		Filter on events
category	string	No		Webhook category
externalId	string	No		Webhook external ID
externalAccountId	string	No		Webhook external account ID
externalUserId	string	No		Webhook external user ID
tags	object	No		Webhook tags (dictionary)
unlisted	boolean	No		Mark Webhook as unlisted
isolationMode	boolean	No		Run the task in isolation mode
isolationKey	string	No		Isolation key
includeFullPayload	boolean	No		Include full task payload (default = false)
includeSensitive	boolean	No		Override default to turn off sensitive data in return data

Secret configuration

Each webhook can contain a secret, used for the HMAC validation.

Secret properties:

Property	Type	Required	Description
name	string	Yes	Secret name
secretReference	string	No	Global secret reference (recommended)
value	string	No	Secret value (not recommended)

While it is technically possible to define a secret value directly in the webhook configuration, it is highly recommended to use globally defined secrets in Taskurai and reference them in the webhook.

options:
  ...
secrets:
  - myglobalcontainerregistrypassword
  - myglobalsecret
workers:
  TestWorker:
    container:
      ...
      passwordSecretReference: containerregistrypassword
      ...
    secrets: 
      - name: containerregistrypassword
        secretReference: myglobalcontainerregistrypassword
      - name: mycontainersecret
        secretReference: myglobalsecret
    environment:
      - name: ENV_WITH_SECRET
        secretReference: mycontainersecret
      - name: ENV_WITH_VALUE
        value: myvalue
      ...

Notice that the global Taskurai secret can only be referenced in the container secret configuration. To use secrets within the container itself, the local secrets defined in the worker should be used.

Events

The following constructs are available to filter on events:

• *.*: Include all commands and any completion status.
• *.status: Include all commands and specified completion status.
• command.*: Include specified command and any completion status.
• command.status: Include specified command and specified completion status.

The following final completion status options are available:

Status	Description
Expired	Task is expired
Succeeded	Task is succeeded
Timeout	Task is timed out
Failed	Task is failed
Fatal	Task is fatal
Canceled	Task is canceled

When no events are specified, all tasks with any final completion status will match.

For example, the following event filter specifies command UploadDailySalesSAP with completion status Succeeded:

UploadDailySalesSAP.Succeeded