About webhooks

Webhooks in Taskurai provide a mechanism to send task completion events to external systems or subscribers in real-time. When a task is completed, Taskurai triggers an outgoing webhook to notify the specified endpoint. This allows seamless integration with external applications. The webhook system is durable and supports retries to ensure reliable delivery, even in cases of temporary endpoint unavailability.

Payload mode

By default when reporting task completion status, only the operation status of a task is reported (condensed mode). It is possible to configure a webhook entry to support full mode, including the whole task payload.

Message format

Taskurai uses the CloudEvent 1.0 Specification as its message format. Any webhook message sent by the webhooks mechanism is wrapped in a CloudEvents envelope.

Example of a condensed task payload:

{
  "specversion": "1.0",
  "id": "f11e6e4b-dd56-42ed-b201-83f95c669169",
  "source": "/accounts/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resources/Buildby.Taskurai/instances/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/webhooks/UploadDailySalesSAP",
  "type": "Taskurai.Task.TaskCompletedEvent",
  "time": "2026-04-01T14:33:53.2339287Z",
  "datacontenttype": "application/json",
  "subject": "tasks/dd629969-79a9-40d1-bd9f-7a34aec1b0a7",
  "traceparent": "00-dd62996979a940d1bd9f7a34aec1b0a7-ee404a29beddd02e-01",
  "payloadmode": "condensed",
  "data": {
    "id": "dd629969-79a9-40d1-bd9f-7a34aec1b0a7",
    "command": "UploadDailySalesSAP@1",
    "created": "2026-04-01T14:33:39.3207933+00:00",
    "modified": "2026-04-01T14:33:53.2339287+00:00",
    "started": "2026-04-01T14:33:40.2112841+00:00",
    "runStarted": "2026-04-01T14:33:40.2112939+00:00",
    "stopped": "2026-04-01T14:33:53.2339287+00:00",
    "status": "Succeeded",
    "taskStatus": "Succeeded",
    "statusCode": 200,
    "archived": false,
    "postponed": false,
    "deleting": false
  }

Example of a full task payload:

{
   "specversion":"1.0",
   "id":"0e56f7e5-b03a-46ca-8705-c803a644d262",
   "source":"/accounts/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/resources/Buildby.Taskurai/instances/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/webhooks/UploadDailySalesSAP",
   "type":"Taskurai.Task.TaskCompletedEvent",
   "time":"2026-04-01T15:03:15.5890747Z",
   "datacontenttype":"application/json",
   "subject":"tasks/9f7f31cc-22a0-4a58-8744-821f77aee3f0",
   "traceparent":"00-9f7f31cc22a04a588744821f77aee3f0-137e61478c319be5-01",
   "payloadmode":"full",
   "data":{
      "accountId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "instanceId":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "id":"9f7f31cc-22a0-4a58-8744-821f77aee3f0",
      "config":{
         "id":"9f7f31cc-22a0-4a58-8744-821f77aee3f0",
         "command":"UploadDailySalesSAP@1",
         "arguments":[
            {
               "name":"date",
               "data":"2026-04-01T15:02:59.030615+00:00"
            },
            {
               "name":"dailySales",
               "stateReference":{
                  "stateStoreName":"DefaultStateStore",
                  "id":"isolation::dd10b001-addd-45c2-94a6-932282b7515c::task::9f7f31cc-22a0-4a58-8744-821f77aee3f0::state::dailysales"
               }
            }
         ],
         "secrets":[
            
         ],
         "category":"Retail sales",
         "tags":{
            
         },
         "subject":"Upload daily sales and send aggregates to SAP.",
         "isolationMode":true,
         "isolationKey":"dd10b001-addd-45c2-94a6-932282b7515c",
         "correlationId":"9f7f31cc-22a0-4a58-8744-821f77aee3f0",
         "traceParent":"00-9f7f31cc22a04a588744821f77aee3f0-023348444ab88dbd-01"
      },
      "created":"2026-04-01T15:03:01.6678302+00:00",
      "createdBy":"d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
      "modified":"2026-04-01T15:03:15.7100041+00:00",
      "modifiedBy":"d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
      "started":"2026-04-01T15:03:02.3712114+00:00",
      "runInitialStart":"2026-04-01T15:03:02.3712114+00:00",
      "runStarted":"2026-04-01T15:03:02.3712236+00:00",
      "stopped":"2026-04-01T15:03:15.5890747+00:00",
      "status":"Succeeded",
      "statusCode":200,
      "progress":{
         "percentage":100.0,
         "message":"Successfully aggregated daily sales.",
         "heartbeat":"2026-04-01T15:03:15.29511+00:00"
      },
      "result":{
         "messages":[
            {
               "code":"200",
               "message":"Successfully aggregated daily sales and uploaded to SAP."
            }
         ],
         "outputs":[
            {
               "name":"dailySalesAggregate",
               "stateReference":{
                  "stateStoreName":"DefaultStateStore",
                  "id":"isolation::dd10b001-addd-45c2-94a6-932282b7515c::task::9f7f31cc-22a0-4a58-8744-821f77aee3f0::state::dailySalesAggregate"
               }
            }
         ]
      },
      "archived":false,
      "postponed":false,
      "deleting":false,
      "runCount":1,
      "taskSpanId":"de952814eec4854c",
      "runSpanId":{
         "1":"e41eb3b1af6f49f8"
      },
      "correlationId":"9f7f31cc-22a0-4a58-8744-821f77aee3f0",
      "hubName":"DefaultHub",
      "workerName":"TestWorker",
      "taskuraiSDKVersion":"2.5.17.0",
      "taskuraiWorkerSDKVersion":"2.5.17.0",
      "defaultStateStore":"DefaultStateStore"
   }
}

HTTPS and SSL verification

The webhook endpoint must use a HTTPS connection. Taskurai will verify SSL certificates when delivering webhooks.

warning

To prevent accidental exposure of sensitive information, avoid including API keys or authentication credentials in your webhook payload URLs. Instead, validate Taskurai webhook deliveries using the provided secret to ensure they are authentic and untampered.

Validating webhook deliveries

Taskurai uses a secret token to create a hash signature, included in each webhook message using the X-Taskurai-Content header.

To validate the message:

Calculate a hash using your secret token and the received payload.
Compare the calculated hash with the signature provided in the header.

How to Validate Signatures

Shared Secret: When creating a webhook entry, you can provide your own shared secret, or Taskurai can generate a random secret for you.
Hash Computation: Taskurai uses HMAC-SHA256 to compute a hash of the payload.
Signature Format: The X-Taskurai-Content header contains the signature in the format sha256=<hash>. Always remove the sha256= prefix before performing the comparison.
Payload Encoding: Ensure the payload is handled as UTF-8 when calculating the hash.
Constant-Time Comparison: Use a "constant time" string comparison method to mitigate timing attacks. For example, in C#, use CryptographicOperations.FixedTimeEquals.

warning

Keep the shared secret token secure. Copy the token to a secure place and do not share or check this token into source control.

Retry behavior

When a webhook endpoint is not able to accept the message, due to network failures, time-out, rate limits, the following retry policy is in place:

Policy	InitialDelaySec	MaxRuns	MaximumDelaySec	RetryMode
Timeout	2	20	240	Exponential

Isolation mode

Webhooks support isolation mode. When webhooks are created in isolation mode, only tasks that are created in the isolated session will be handled by webhook. When listing webhooks in isolation mode, by default, only items belonging to the isolated session will be returned.

Payload mode​

Message format​

HTTPS and SSL verification​

Validating webhook deliveries​

How to Validate Signatures​

Retry behavior​

Isolation mode​