About Webhooks
Webhooks allow you to build or set up integrations, which subscribe to certain events in Integrator. When one of those events is triggered, we'll send a HTTP POST or GET request to the webhook's configured URL. Webhooks can be used to update your external system about events happening in the Integrator.
Creating a Webhook
Only users with 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.
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 this webhook requestX-Etl-Webhook-Event
- the name of the event that triggered this webhook requestX-Etl-Webhook-Id
- the ID if the webhookX-Etl-Webhook-Entity-Id
- the ID of the object that was affected during this event. For example if event isFlow.Created
then it will be 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, that will contain all the information related to the event happened in the system.
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 thePOST
request. 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. Payload example:
-
eventId=32f54fa6-41ae-432e-a720-4373bdf72e6d&eventType=Flow.Executed&webhookId=1&entityId=11157×tamp=1588165500224
Include Entity
If Include Entity is selected, then all entity data will be included into the payload. Note that entity ID will be specified in the payload regardless of this option.
Enabled
By default, webhook are "Enabled" You can choose to temporary 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 chose to receive webhooks on All events, or click on Select individual events and then select only those events that you are interested in.
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 to the one received in the X-Etl-Webhook-Signature
header.
Basic Authentication
If your endpoint is protected by Basic Authentication, you can provide username and password. Webhook will make sure to set 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
Debugging a Webhook
After you created your webhook(s) you can inspect recent deliveries by clicking on "View events".
"View events" lets you see last 100 events of each webhook .By expanding an individual delivery, you'll be able to witness precisely what information Integrator is attempting to send to your server. This includes both the HTTP Request and Response headers and payload.
Comments
0 comments
Please sign in to leave a comment.