Webhooks API

Create, manage, and retrieve webhook definitions.

Overview

Use webhooks to register your own HTTPS endpoints with Visier and listen for specific events. Webhooks can listen for the following event types:

• A successful job.
• A failed job.
• A rescheduled job.
• A published data version.

When the configured event type occurs, Visier sends an API request to your registered endpoint. For example, you can use webhooks to push job event results directly to you instead of polling job statuses.

The maximum number of webhooks is 20.

With this API, you can:

• Retrieve a list of all webhooks
• Create new webhooks
• Update existing webhooks
• Delete webhooks
• Test that a webhook works

Best practices

Only listen for integration-related events

We recommend that your webhooks only listen for the event types required to integrate with Visier. Listening for non-required events can place unnecessary load on your system.

Respond to Visier's notification quickly

Configure your endpoint to respond to Visier's webhook notification in a timely manner, such as 3 to 5 seconds. If your endpoint doesn't send a response, Visier marks the notification as failed. Visier retries the notification up to 3 times. Your endpoint should return a successful response before performing complex logic to avoid timing out.

Verify that the message came from Visier

Make sure you confirm that the message came from Visier. In every webhook notification from Visier, we attach a signature in the x-visier-signature header. The signature is generated from the encryption key associated with the webhook. To verify the message came from Visier:

1. Extract the x-visier-signature header value.

2. Prepare the payload. This is the raw request body from Visier; for example: 

   Copy

   Sample webhook raw request body

   1
   {"timestamp": "1743718453610","eventId": "c0c91580-ce09-40fd-8f84-39d8578c704b","eventType": "jobResultSuccess","event": {"jobid": "00000000-0000-0000-0000-000000000000","rootJobId": "00000000-0000-0000-0000-000000000000","parentJobId": "00000000-0000-0000-0000-000000000000","tenantCode": "WFF_j1r","jobType": "","dataCategoryId": "00000000-0000-0000-0000-000000000000","dataVersion": ""}}

3. Compute the HMAC value using the SHA256 hash function. Use the configured secret as the key and the payload as the message.
4. Compare the signature to the signature extracted from the header. The values must match. If the values don't match, ignore the message.

Example

Let's say you want to automate your data processing to monitor running jobs and alert you when a job successfully completes or fails. In this scenario, you can set up one webhook that listens for job success and job failure events.

1. Set up an HTTPS endpoint that Visier can call, such as https://my.webhook.com. Make sure the endpoint will quickly respond to Visier's calls, such as returning a successful 2XX response, before performing complex logic.
2. Create credentials that Visier can use to authenticate with the endpoint. The credentials can be a username and password or an access token. Not required if your endpoint doesn't have authentication. In this example, we'll use the access token g1v3m34cc355.
3. Generate an encryption key to associate with the webhook using the HMAC-SHA256 algorithm. You can use the Encryption Keys API to generate an encryption key. In this example, the encryption key is webhook_key. For more information, see "Encryption Keys" in API Reference.
4. Create a webhook with Visier. In this example, the request might look like the following code sample.

   Note: When creating a webhook, set isActive to false. After you verify that the webhook works and you are ready to receive notifications, set isActive to true using the PUT endpoint.

   Copy

   Code sample: Create a job success and job failure webhook for https://my.webhook.com

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   curl -X POST --url 'https://jupiter.api.visier/v1beta/op/webhooks' \
   -H 'apikey:12345' \
   -H 'Cookie:VisierASIDToken=abc123' \
   -H 'Content-Type: application/json' \
   -d '{
       "details": {
           "targetUrl": "https://my.webhook.com",
           "isActive": false,
           "events": [
               {"eventType": "jobResultSuccess"},
               {"eventType": "jobResultFailure"}
           ],
           "keyName": "webhook_key",
           "displayName": "webhook_name"
       },
       "credentials": {
           "accessToken": "g1v3m34cc355"
       }
   }'

5. Test that the webhook works. Send a test event to the webhook and check that you receive a notification from Visier. In this example, let's say the webhook ID is webhook1. The test request might look like the following code sample.
   Copy

   Code sample: Test the webhook

   1
   2
   3
   4
   5
   6
   7
   curl -X POST --url 'https://jupiter.api.visier/v1beta/op/webhooks/webhook1/testEvent' \
   -H 'apikey:12345' \
   -H 'Cookie:VisierASIDToken=abc123' \
   -H 'Content-Type: application/json' \
   -d '{
       "eventType": "jobResultSuccess"
   }'

6.  Confirm that the message came from Visier. For more information, see Verify that the message came from Visier.
7. Set up logic to process the notification. In this example, we want to set up logic for job failures that automatically creates a support ticket to investigate the failure (excluding rescheduled jobs) and no action for job successes.

8. Turn the webhook on. Because you've verified that the webhook works and you're ready to receive notifications, you can update the webhook to active. In this example, the request might look like the following code sample.

   Copy

   Code sample: Set the webhook to isActive: true.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   curl -X PUT --url 'https://jupiter.api.visier.io/v1beta/op/webhooks/webhook1' \
   -H 'apikey:12345' \
   -H 'Cookie:VisierASIDToken=abc123' \
   -H 'Content-Type: application/json' \
   -d '{
       "webhookId": "webhook1",
       "details": {
           "targetUrl": "https://www.my.webhook.com",
           "isActive": true,
           "events": [
               {"eventType": "jobResultSuccess"},
               {"eventType": "jobResultFailure"}
           ],
           "keyName": "webhook_key",
           "displayName": "webhook_name"
       },
       "credentialReference": "2e4e6a6d-1500-4697-8a45-7285e3887d13"
   }'