A webhook is a user-defined HTTPS callback that is triggered when a particular event occurs in a KB record. The webhook receives real-time notification messages for events. When the event happens, the service makes an HTTPS POST request to the webhook's HTTPS URL.

Webhooks are useful when you want to receive and process real-time data updates. Instead of needing to make a REST API call to check for changes, when you register webhooks in your KB, the service automatically pushes HTTPS POST event notifications to the webhook's URL to tell the webhook the event has occurred. This push-based model requires fewer API requests overall and provides real-time updates with simpler build. With webhooks, you can build more robust apps and update your application instantly.

Agiloft webhook notifications are generated when a record is created, edited, or deleted. The event notification includes updated information about the field values that were selected in your webhook configuration. Optionally, these notifications can also include detailed information like status changes.

To create and initialize a webhook:

1. Either the client application calls POST /ewws/webhooks with a user token to register the webhook as a resource, or you create a webhook manually in Setup > Integration > Webhooks Setup.
2. Agiloft validates that the POST request is valid and the webhook URL is valid. There is a special processing for this validation where Agiloft makes the HTTPS GET request to your webhook URL, and the webhook URL is expected to respond in a specific way. For details, see Verifying the Webhook URL.
3. Agiloft sends the success response with an HTTP 2XX code to your client application (if you are using a REST API call) with a unique webhook identifier and Location header, which contains the URL of the webhook resource. This URL is created in Webhooks Setup in your KB.
4. Going forward, whenever the specified event happens in your KB, a notification for that event is sent to the webhook URL.

Configuring Webhooks

Webhooks can be created using REST APIs, or built directly in your KB from Setup > Integration > Webhooks Setup. When you access it for the first time, Webhooks Setup shows a Deploy button; after you click that and webhooks are successfully deployed, click Configure to access webhooks. The table is empty to begin with, but going forward, any webhook you create will appear in this list, whether it was created manually in Webhooks Setup or registered using a REST API call.

Each webhook entry sets the following properties:

Creating Webhooks in  Agiloft

You can create a new webhook directly in  Agiloft. To do so:

1. Go to Setup > Integration > Webhooks Setup and click Deploy, then click Configure when the deployment is complete.
2. In the Webhooks Setup page that opens, click New to create a new webhook.
3. Complete all the fields, which correspond to each of the parameters described above.
4. Once you have entered all required data, click Save.
5. To activate your webhook, click Enable.

When you enable a new webhook, Agiloft makes the HTTPS GET request to your webhook URL. The webhook URL is expected to respond in a specific way. If the URL responds correctly, Agiloft automatically makes the webhook Active, and it's ready for you to use.

If you need to deactivate the webhook later, simply click Disable for that entry in the list. Always disable a webhook before you delete it in Webhooks Setup. Otherwise, if you remove the entry from the list without deactivating the webhook, the webhook remains active until the next time the KB restarts.

Creating Webhooks with REST API

You can also create webhooks using a REST API call instead of the Webhooks Setup menu.

This can be done by calling the POST /ewws/webhooks API from your application and passing along the subscription data. The subscription specifies how the webhook intends to consume events. For details about constructing the API call, see the parameters described in the Register API section.

When Agiloft receives a webhook creation request from your application, the Webhook service first verifies the webhook URL by making a GET call it. If that call succeeds, the Webhook service  returns the response of the POST call, with the URL of the newly created webhook resource contained in the HTTPS Location header. The client service can later make PUT/GET/DELETE calls on this URL. See the list of API calls for webhook management below.

Verifying the Webhook URL

Before registering a webhook configuration successfully, Agiloft verifies that the provided webhook URL is able to receive event notifications. To test this, when a new webhook registration request is received, Agiloft makes a verification request to the webhook URL. This verification request is a HTTPS GET request. This request has a custom HTTP header, WH_verification_code. The value in this header is set to the random generated code that is requesting to create and register the webhook. To successfully register a webhook, the webhook URL must respond to this verification request with the 2XX response code in one of two ways:

• In a response header, WH_verification_code. This is the same header which was passed in the request, and can be echoed back in the response.
• In JSON response body with the key of WH_verification_code, its value being the same as in the WH_verification_code header that was sent in the request.

The webhook is registered only if the URL successfully sends the 2XX response code as expected. If you accidentally enter an incorrect webhook URL, the URL will fail to respond correctly to the verification of intent request, and Agiloft will not send any notifications to that URL.

In addition, the webhook URL can also validate that it would receive notifications only through the webhooks which are registered by a specific application. This can be done by validating the verification codes that are passed in the WH_verification_code header. If the webhook URL does not recognize that verification code, it must not respond with the success response code, and Agiloft will take care that the provided URL is not registered as a webhook.

Webhook URL calls are always verified when:

• Creating (registering) the Webhook entry. If this verification of webhook URL call fails, the webhook will not be created.
• Updating (changing) the Webhook entry. This changes a webhook's status from Inactive to Active. If this verification of webhook URL call fails, the webhook status will not be changed to Active.

Responding to Webhook Notifications

The Agiloft webhook service performs an implicit verification of the webhook URL in each webhook notification request that is sent. Therefore, every webhook notification HTTPS request also contains the custom HTPS header called WH_verification_code. The value of this header is the same value of WH_verification_code (the random generated key) as described in Verifying the Webhook URL.

The Webhook service considers the webhook notification successfully delivered using the same criteria as the initial registration. Otherwise, the Webhook service reattempts delivery  of the notification to the webhook URL until the retries are exhausted.

Webhook REST API

This section details the REST API calls specific to using webhooks.

Registering Webhooks

The client application makes an HTTPS POST call to the /ewws/webhooks endpoint, using an OAuth access token, JWT token, or user credentials as authentication, and including the following parameters:

Error Codes

This list covers common error codes, but not all. Note that new error codes might be added later, and existing error codes might be updated. Your application should be prepared to do default handling for error scenarios.

See also the Format of error response section for details.

Retrieving Webhook Information by Webhook Key

The client application makes an HTTPS GET call to the /ewws/webhooks endpoint, using an OAuth access token, JWT token, or user credentials as authentication, and including the following parameters:

Error codes

This list covers common error codes, but not all. Note that new error codes might be added later, and existing error codes might be updated. Your application should be prepared to do default handling for error scenarios.

See also the Format of error response section for details.

Retrieving the List of Webhooks

The client application makes an HTTPS GET call to the /ewws/webhooks endpoint, using an OAuth access token, JWT token, or user credentials as authentication, and including the following parameters:

Error codes

This list covers common error codes, but not all. Note that new error codes might be added later, and existing error codes might be updated. Your application should be prepared to do default handling for error scenarios.

See also the Format of error response section for details.

Updating the Webhook

The client application makes an HTTPS PUT call to the /ewws/webhooks endpoint, using an OAuth access token, JWT token, or user credentials as authentication, and including the following parameters:

Error codes

This list covers common error codes, but not all. Note that new error codes might be added later, and existing error codes might be updated. Your application should be prepared to do default handling for error scenarios.

See also the Format of error response section for details.

Activate or Deactivate the Webhook

The client application makes an HTTPS PUT call to the /ewws/webhooks endpoint, using an OAuth access token, JWT token, or user credentials as authentication, and including the following parameters:

Error codes

This list covers common error codes, but not all. Note that new error codes might be added later, and existing error codes might be updated. Your application should be prepared to do default handling for error scenarios.

See also the Format of error response section for details.

Deactivating and Removing the Webhook

The client application makes an HTTPS DELETE call to the /ewws/webhooks endpoint, using an OAuth access token, JWT token, or user credentials as authentication, and including the following parameters:

Error codes

This list covers common error codes, but not all. Note that new error codes might be added later, and existing error codes might be updated. Your application should be prepared to do default handling for error scenarios.

See also the Format of error response section for details.

Format of Error Responses

Each response has an HTTPS error status, error code, and error description. The error responses from the webhook service have the following Json format: { "error" : "", "error_description" : "" }

Standard Error Codes

This list covers common error codes, but not all. Note that new error codes might be added later, and existing error codes might be updated. Your application should be prepared to do default handling for error scenarios.