Creating webhooks for the Asta Vision API

You use the Webhooks page to create and manage webhooks, for use with the Asta Vision API.

To access the Webhooks page from the Asta Vision Home page, click Admin then click Webhooks.

A webhook is an HTTP callback that allows an API to automatically send event data to another application when something happens, rather than requiring that application to repeatedly ask for updates. You can use webhooks in conjunction with the Asta Vision API to inform other systems when the following types of event occur in Asta Vision:

  • Project Created - a new project is created in Asta Vision.
  • Project Deleted - a project is deleted permanently within Asta Vision.
  • Programme Checked In - a programme is checked in (including the upload of a programme via the Asta Vision API).
  • Workflow Action - a specific workflow action is executed, for example a new baseline of a programme is created, or the status of a project is changed to a specific value.
  • Programme BI Generated - your Business Intelligence database is updated.
  • Advanced BI Generated - your advanced Business Intelligence database is updated.

Once you have created a webhook, each time an event of the appropriate type occurs, the Asta Vision API automatically sends a POST HTTP request to the URL that has been specified in the webhook, containing the ID of the subscription, the event type, and the event data:

{

"subscriptionId" : "{Guid}"

"eventType" : "{Vision event e.g. 'projectCreated'}"

"projectGuid" : "{Guid of project if applicable}"

"programmeGuid" : "{Guid of programme if applicable}"

"workflowActionId" : "{Id of workflow action if applicable}"

"programmeVersion" : "{Version number of the programme for this event}"

}

Webhooks that relate to project creation or BI generation send notifications when the event in question has been completed, rather than when it starts, to ensure that external applications can access the required data immediately.

To create a webhook:

  1. On the Webhooks page, click Create Webhook. The Webhook details page appears.
  2. Use the fields on the page to set up the webhook - see below for details of the fields on the page.
  3. Click Create. You return to the Webhooks page, where the new webhook appears in the list.

Creating a webhook in this way has the same effect as sending a 'POST' HTTP request to the /webhooks/subscribe URI.

To edit a webhook:

  1. On the Webhooks page, click the name of the webhook that you want to edit. The Webhook details page appears.
  2. Use the fields on the page to edit the webhook - see below for details of the fields on the page.
  3. Click Save Changes. You return to the Webhooks page.

Every time a webhook fails, an error is reported and its 'fail count' is incremented by one. You can view information on webhook successes and failures, which can help to diagnose issues with a webhook.

To view information on webhook successes and failures:

  1. On the Webhooks page, click the name of the webhook. The Webhook details page appears, displaying the following information about successes and failures:
    FieldDescription
    Success DateThe date and time at which the webhook was last used successfully.
    Fail DateThe date and time at which the webhook last failed.
    Fail CountThe number of times the webhook has failed since its errors were last reset.
    Last ErrorThe error that was reported when the webhook last failed.
  2. When you have reviewed the success and failure information, click Back to List. You return to the Webhooks page.

Once you have resolved an issue with a webhook, you may want to reset its errors. To do this:

  1. On the Webhooks page, right-click the webhook and select Reset Errors. A popup appears, asking you to confirm whether you want to rest the webhook's errors.
  2. Click OK to reset the webhook's errors and return to the Webhooks page. The webhook's fail count is reset, and the its fail date and information on the last reported error are cleared.

If you delete a webhook, it becomes invalid and is no longer usable.

To delete a webhook:

  1. On the Webhooks page, right-click the webhook that you want to delete and select Delete. A popup appears, asking you to confirm whether you want to delete the webhook.
  2. Click OK to delete the webhook and return to the Webhooks page.

Deleting a webhook in this way has the same effect as sending a 'DELETE' HTTP request to the /webhooks/unsubscribe/{subscriptionId} URI.

Field Description
Subscription ID

The webhook's identifer.

 

This field appears only when you edit an existing webhook.
Name Enter a descriptive name for the webhook you are creating or editing.
Event Type

Specify the type of event about which this webhook will notify an external system. For example, if you want to use the webhook to notify an external system each time a project is created, select 'Project Created' in this field.

 

Depending on the type of event you select, additional fields may appear.
URL

Enter the internet address that should receive notifications from the webhook, for example 'https://myapp.com/webhooks/a1', or 'https://api.company.com/events/programme_checked_in'.

 

When the specified type of event occurs, the Asta Vision API makes an HTTP 'POST' request to the specified URL.
Headers

A list of additional headers that are required for the webhook to work. For example, you might need to add a header to a webhook to enable it to get through a firewall.

 

To add a header to a webhook:

  1. Click Add Header. Name and Value fields appear.
  2. Enter the name of the header in the Name field.
  3. Enter the value to apply to the header in the Value field.

You can define more than one header for each webhook. If you need to define more than one header, click Add Header again and enter its details in the fields that appear.

 

Click Remove to the right of a header to remove it from the list if required.
Workflow Action

To make the webhook apply to all workflow actions, leave this set to 'All Actions'; select a specific workflow action to make the webhook apply to that action only.

 

This field appears only when 'Workflow Action' is selected in the Event Type field.
Project Filter

To make the webhook apply to all projects, leave this set to 'All Projects'; to make the webhook apply to a specific project, click Select, then select a project using the Select Project dialog that appears.

 

This field does not appear for all event types.
Programme Filter

With a specific project selected, to make the webhook apply to all programmes, leave this set to 'All Programmes'; select a specific programme to make the webhook apply to that programme only.

 

This field does not appear for all event types.

The following additional fields appear when you view details of an existing webhook. You can use this information to help diagnose any problems with the webhook:

Field Description
Success Date The date and time at which the webhook was last used successfully.
Fail Date The date and time at which the webhook last failed.
Fail Count The number of times the webhook has failed since its errors were last reset.
Last Error The error that was reported when the webhook last failed.

Related Topics:

Introduction to the Asta Vision API

Understanding API terminology

Using the API Portal to learn about and construct HTTP requests

Operations available in the Asta Vision API