Skip to main content

Webhooks

Webhooks are HTTP callbacks that are triggered by events in DX Engine. They can be used for a variety of purposes, including sending event information to your logging system.

All Orchestration Components create events, and by default a webhook will run for the selected event type on all Components. If you want to restrict your webhook to a particular Component or set of Components, use the Trigger Expression. You can then set logic in the Body to determine how to handle the payload.

Webhooks Management in DX Engine​

Webhooks can be managed through the DX Engine UI. Navigate to Settings -> Webhooks. Click + Add Webhook to create a new Webhook or select an existing Webhook from the listing to edit, delete, or duplicate.

To set up a new Webhook, follow these steps:

  1. Enter Webhook code and name. Optionally, enter a description.
  2. Select the event type that you want the Webhook to be triggered for. Options include: requestCompleted, asyncRequestCompleted, componentCompleted, componentFailed, componentValid, componentInvalid, componentSkipped, configurationUpdated
  3. Check the Enabled box to mark the Webhook as active.
  4. Enter a Trigger Expression that will be evaluated to determine if the Webhook should be triggered.
  5. Specify the endpoint and method for the Webhook.
  6. Pass required information through headers, query params, or in the body.

payload and eventTypes are available in the JS Expressions, as well as the secret() and environmentVariable() functions.

Webhook Form Webhook Form Webhook Form

Available eventTypes:

[
    'requestCompleted',
    'asyncRequestCompleted',
    'componentCompleted',
    'componentFailed',
    'componentValid',
    'componentInvalid',
    'componentSkipped',
    'configurationUpdated'
]

A sample payload structure:

{
 "engineRequestId": "",
 "context": {},
 "duration": 274,
 "@debug": {
   "evaluatedConfig": {...},
   "context": {...},
   "requestConfig": {...},
   "evaluatedValidity": true,
   "evaluatedContextFieldEnrichment": {},
   "evaluatedTrigger": true,
   "processingDuration": 274,
   "processingStartTime": 1721929995359
 },
 "componentCode": "",
 "@extras": {
   "rule": {
     "metadata": [],
     "attributes": {}
   }
 },
 "status": "",
 "response":{...},
 "customerCode": "",
 "environmentCode": ""
}

The event type requestCompleted has a slightly different payload than other eventTypes. It is very similar to the response that is returned via the API or what you see on the debug page.

{
 "componentA": {
   "@debug": {},
   "@extras": {},
   "status": "VALID",
   "response": {}
 },
 "componentB": {
   "@debug": {},
   "@extras": {},
   "status": "VALID",
   "response": {}
 }
}

Webhooks Management API​

Create a Webhook​

PUT {{engineUrl}}/webhooks
X-Customer-Code: {{customerCode}}
X-Environment-Code: {{environmentCode}}
Authorization: Bearer {{dxEngineToken}}

{
    "webhookCode": "test",
    "name": "Logging Webhook",
    "eventType": "componentValid",
    "enabled": true,
    "triggerExpression": "`{{expression}}`",
    "endpoint": {
        "method": "POST",
        "queryParamsOptions": {
            "encode": true,
            "arrayFormat": "none",
            "arrayFormatSeparator": ",",
            "skipNull": true,
            "skipEmptyString": false
        },
        "url": "https://webhook.site/4fdebbe8-6045-4b1b-949e-f01a3c53a88d",
        "body": "`_.assign({}, {'response': payload.response, 'debug': payload['@debug']})`"
    }
}

Update a Webhook​

PUT {{engineUrl}}/webhooks/{{webhookCode}}
X-Customer-Code: {{customerCode}}
X-Environment-Code: {{environmentCode}}
Authorization: Bearer {{dxEngineToken}}

{
    "webhookCode": "test",
    "webhook": {
      "name": "Logging Webhook (Disabled)",
      "eventType": "componentValid",
      "enabled": false,
      "triggerExpression": "`{{expression}}`",
      "endpoint": {
          "method": "POST",
          "queryParamsOptions": {
              "encode": true,
              "arrayFormat": "none",
              "arrayFormatSeparator": ",",
              "skipNull": true,
              "skipEmptyString": false
          },
          "url": "https://webhook.site/4fdebbe8-6045-4b1b-949e-f01a3c53a88d",
          "body": "`_.assign({}, {'response': payload.response, 'debug': payload['@debug']})`"
      }
    }
}

Fetch a Webhook​

GET {{engineUrl}}/webhooks/{{webhookCode}}
X-Customer-Code: {{customerCode}}
X-Environment-Code: {{environmentCode}}
Authorization: Bearer {{dxEngineToken}}

Remove a Webhook​

DELETE {{engineUrl}}/webhooks/{{webhookCode}}
X-Customer-Code: {{customerCode}}
X-Environment-Code: {{environmentCode}}
Authorization: Bearer {{dxEngineToken}}