Create and Manage Webhooks

Overview

Webhooks allow you to build or set up integrations, which subscribe to certain events in Etlworks. When one of those events is triggered, we'll send an HTTP POST or GET request to the Webhook's configured URL. Webhooks can be used to update your external system about events happening in Etlworks.

Create a Webhook

Only users with the Administrator role can create Webhooks. To set up a Webhook, go to the Webhooks page of your account. From there, click Add webhook.

Alternatively, you can choose to build and manage a Webhook through the Webhooks API.

Webhooks require a few configuration options before you can make use of them. We'll go through each of these settings below.

URL

The payload URL is the URL of the server that will receive the webhook POST or GET requests.

Note: The URL can be empty if the webhook triggered by the event is meant to send theNote: email notificationNote: only.

Method

The Webhook can make either POST or GET requests to your server. Regardless of your choice, you will receive several headers in the Webhook request:

• X-Etl-Webhook-Event-Id: unique ID of a Webhook request.
• X-Etl-Webhook-Event: the name of the event that triggered a Webhook request.
• X-Etl-Webhook-Id: the ID of the Webhook.
• X-Etl-Webhook-Entity-Id: the ID of the object that was affected during an event. For example, if the event is Flow.Created then it will be the ID of the newly created Flow.
• X-Etl-Webhook-Entity-URL: the API URL that can be used to retrieve the entity.

If you select POST method for your Webhook, then you will also receive a payload as the body of the request which contains all the information related to the event that happened in the system.

Email

The comma-separated list of email addresses to send the nofification to when the webhook is triggred by the event.

Content type

Webhooks can be delivered using different content types:

• The application/json content type will deliver the JSON payload directly as the body of the Post request. Here's a payload example:

• {
    "eventId": "7027e72b-9005-4fcc-8385-8da47249136a",
    "eventType": "Flow.Executed",
    "webhookId": 1,
    "entityId": 11225,
    "entity": {
      ...
    },
    "entityUrl": "https://app.etlworks.com/rest/v1/flows/1?auditId=11225",
    "timestamp": 1588429200207
  }

• The application/x-www-form-urlencoded content type will send the payload as URL encoded form parameters. Here's a payload example:

• eventId=32f54fa6-41ae-432e-a720-4373bdf72e6d&eventType=Flow.Executed&webhookId=1&entityId=11157&timestamp=1588165500224

• The Slack Incoming Webhook content type will send payload in the Slack Block Kit format and can be used to setup Slack integration, read more here.

Include Entity

If Include Entity is selected, then all entity data will be included in the payload. Note that an entity ID will be specified in the payload regardless of this option.

Enabled

By default, Webhooks are enabled. You can choose to temporarily disable the delivery of Webhook payloads by deselecting Enabled.

Events

Events are at the core of Webhooks. These Webhooks fire whenever a certain action is taken in the system. You can choose to receive Webhooks on All events, or click on Select individual events and then select only those events that you are interested in.

The following events are available:

At the Super Admin level additional events can be selected:

Custom Payload Template

Optional payload template. Template can contain tokens represented by the default JSON payload attribute name surrounded by the double curly braces. To access entity object attributes use 'entity' dot entity attribute name, for example: 'entity.name'. Each token will be replaced with actual values. These are always available attributes: eventId, eventType, webhookId, entityId, entityUrl, timestamp. Entity attributes differ based on the event type.

Include and Exclude flows

All webhooks triggered by an event associated with a flow (for example, Execute) can now include a list of flows to include or exclude.

Secret

Setting a Webhook secret allows you to ensure that POST requests sent to the payload URL are from Etlworks and weren't tempered with. When you set a secret, you'll receive the X-Etl-Webhook-Signature header in the Webhook POST request.

The value of that header is equal to the HMAC SHA-1 hash signature of the payload (request body). To verify the request, you can calculate the signature of the payload on your side using the same secret and compare it to the one you received in the X-Etl-Webhook-Signature header.

Basic Authentication

If your endpoint is protected by Basic Authentication, you can provide a username and password. Webhook will make sure to set the proper authentication header on the request.

Custom Headers

Custom headers allows you to specify any number of additional headers you would like to be set on the Webhook request

Run a Simba task from a webhook (10.0.8+)

Administrators (Super Admin or Tenant Admin) can set Run Simba task in the webhook editor to a Run Simba Prompt flow in the same tenant. The webhook then triggers that flow using the approving admin's identity and the flow's saved permissions; results are stored in flow execution history, and result emails are configured on the flow.

• Saving forces POST with application/json. A webhook with a Simba task cannot also deliver to URL/email — use a separate webhook for that.
• Delivery history records a 202 status with an X-Etl-Simba-Audit-Id header; the event payload is capped at 64,000 characters.
• Duplicate deliveries do not start a second run; an overlapping run is rejected; Simba-generated events do not trigger other Simba targets.

Enable or disable a webhook from the list (10.0.8+)

Each row of the Webhooks list has an inline enable/disable checkbox that saves immediately without discarding unsaved editor changes; disabled rows are greyed out. Webhook changes — including enable/disable — are recorded in the Audit Trail (addWebhook, editWebhook, deleteWebhook, setWebhookEnabled); secrets, authentication, URLs/emails, headers, and templates are excluded from audit records.

Debug a Webhook

 After you created your Webhook(s), you can inspect recent deliveries by clicking on View events.

View events lets you see the last 100 events of each Webhook. By expanding an individual delivery, you'll be able to witness precisely what information Etlworks is attempting to send to your server. This includes both the HTTP Request and Response headers and payload.