Webhooks

Updated: June 3, 2020
Contents

Webhooks are used to automate the processing of asset requests in Connect.

Terminology

A Webhook is an object in Connect that watches for the asset requests related to a certain product and triggers an external Webhook Handler through that handler’s API.
A Webhook Handler is an external custom tool that processes asset requests in Connect using the Connect API. It exposes an endpoint URL that the Webhook calls to trigger the Handler.

Video Tutorial

In this video, you will learn how to use webhooks to trigger your product processing.

Processing Methods

Manual Processing

Often, a workflow in Connect cannot complete a process until a provider or vendor performs required actions. Typically, one of those accounts must pay attention to a pending object and process it. For example, in the contract flow, after a vendor requests a distribution contract, the new contract stays pending and waiting for the provider’s approval. Such an event happens not so often and requires manual processing. The provider notices the pending request in the Provider Portal and then either approves or rejects it.

Automatic Processing

In the fulfillment flow, there are a lot of asset requests that require faster processing. In this case, manual processing is not effective, and therefore automatic processing is the best solution. The external processing system can interact with Connect in one of the following modes:

  • Polling: You create a scheduled process that polls periodically an asset request queue in Connect. When this queue changes, the scheduled process triggers the external processing system.
  • Webhooking: Connect enables providers and vendors to create a webhook that watches for the asset request queue of a particular product and triggers the corresponding processing on queue changes.

The latter mode avoids additional polling and this way uses system resources more efficiently.

Operations

A webhook calls an external handler using an HTTP GET or POST request that contains an Authorization header with the bearer attribute whose value is JWT (JSON Web Token) signed by a secret string. A POST request also contains a body. After receiving an API call from the webhook, the handler performs the following typical operations:

  1. Validate the received JWT by calculating the HS256 signature and comparing it with the signature inside the JWT. For this operation, the handler uses a shared JWT secret string that the webhook uses for signing the JWT.
  2. Get filtered asset requests from Connect and analyze whether they must be processed. For example, the following is a request for all pending requests bound to the product specified by its ID:
GET /requests?status=pending&product_id={PRD-ID}
  1. Perform the necessary processing and update the processed asset requests in Connect.

Webhook Creation

Prerequisites

Before you start creating a webhook, ensure you have the following components:

  • A product that you want to process.
  • An external handler that the new webhook must trigger.
  • The API call parameters, including:
    • The endpoint URL
    • The HTTP method, either GET or POST

Creation Process

The following procedure illustrates how a vendor can create a webhook for processing a certain product request queue.

1. Start creating a webhook

On the Extensions main screen, navigate to Webhooks:

Click Create Webhook.

2. Set general parameters

On the pop-up window, enter general parameters:

  • Name: a name of the new webhook
  • Description: a description of the new webhook in the text format with simple markup elements and links
  • Enabled: a switch that turns the webhook on or off

Note

If you are not sure about all webhook parameters yet, keep the disabled state in this step and turn this object on after you create it and clarify all parameters.

Click Next.

3. Select the product

A webhook can serve only one product that you must select in this step:

After you selected a product, click Next.

4. Select a type of request change

From the list of request change types, select one:

  • Asset requests queue changes: The webhook is triggered on any change in the request queue, whether a new request is added or a request state is changed.
  • Draft asset request validations: The webhook is triggered when a request for a product requires dynamic validation. In this case, a pending request waits for its processing.

5. Configure the API call parameters

Configure the API call parameters that the webhook will use when calling the external handler:

  • Endpoint URL: This is the endpoint URL where the handler accepts API calls.
  • JWT secret: A random code that the webhook will use to create the JWT (Java Web Token) HS256 signature. Share this secret with the handler that needs it to validate incoming JWTs.
  • Method: An HTTP method that can be either GET or POST.
  • Headers: Any standard or custom headers that you need to pass in the API call.

After you finished setting call parameters, click Next.

6. Configure additional data

If in the previous step you selected the POST method, then most probably you need to add additional data to pass them to the external handler:

Enter the necessary additional data in the JSON format. Click Create after that.

7. Enable the webhook

If your webhook is still disabled, enable it now:

In the top right corner, open the drop-down menu, and select Enable.

You have completed the webhook creation. At any time, you can open the webhook for editing and update its parameters.

Testing

You can test the webhook using the following ways.

1. Direct triggering

To test the webhook to handler API channel, trigger the webhook directly from its details window:

Click Trigger Now and verify the following:

  • On the Statistics tab, the number of events, triggers, and responses are increased.
  • Your webhook handler received an API request according to the webhook configuration.

2. Product request

Using the Products module, create a test request for the product that is bound with the webhook. Do the same verification as in the previous step. The external handler must receive a request similar to the following (some values are cut for brevity and only one header is displayed):

POST /
Authentication:	Bearer eyJ0eXAiO...UzI1NiJ9.eyJ3ZWJob...M4NDN9._VMzP3Xap...WGh1E0EQ

{
    "webhook_id": "WH-802-754-426",
    "webhook_name": "Video Recorder Processing",
    "object_class": "fulfillment_requests",
    "account_id": "VA-240-990",
    "product_id": "PRD-732-876-580",
    "api_url": "https://api.conn.rocks/public/v1/",
    "triggered_at": "2020-05-27T09:54:03+00:00",
    "last_success_at": null,
    "last_failure_at": "2020-05-27T09:52:32+00:00",
    "processing_timeout": 600,
    "data": {
        "purpose": "demo",
        "audience": "partners"
    }
}

The JWT carries signed trustworthy data similar to the following:

  • JWT header:
{
  "typ": "JWT",
  "alg": "HS256"
}
  • JWT payload:
{
  "webhook_id": "WH-802-754-426",
  "webhook_name": "Video Recorder Processing",
  "object_class": "fulfillment_requests",
  "account_id": "VA-240-990",
  "product_id": "PRD-732-876-580",
  "api_url": "https://api.connect.cloudblue.com/public/v1/",
  "triggered_at": "2020-05-27T09:54:03+00:00",
  "last_success_at": null,
  "last_failure_at": "2020-05-27T09:52:32+00:00",
  "processing_timeout": 600,
  "data": {
    "purpose": "demo",
    "audience": "partners"
  },
  "exp": 1590573843
}

Webhook Management

During their lifecycle, webhooks help their owners to evaluate asset processing and allow them to change webhook configuration as described in the following sections.

General Operations and Properties

In the webhook details screen, pay attention to the following general operations and properties:

  1. Trigger Now is a button that allows you to test the webhook as described in Direct triggering.
  2. Edit is a button that opens the webhook in the edit mode. You can edit the properties that you set during the Creation Process, except for the request change type that you specified in the Select a type of request change step.
  3. The drop-down menu in the top right corner contains two operations that allow you to disable or delete the webhook.
  4. Status displays the current webhook status: You can change it through the disable operation in the menu – item #3 in the above image.
  5. ID is an auto-generated webhook ID that you cannot change.
  6. Product is the product that webhook watches for. You can change it in the editor.
  7. Type displays the type of change requests that the webhook watches for. You cannot change it.
  8. Created is the date and time of the webhook creation.
  9. Modified is the date and time when the webhook was last updated.

Statistics

The Statistics tab enables the webhook owner to evaluate the asset processing using the following parameters:

  • Events: the number of asset requests that triggered the webhook.
  • Triggers: the total number of attempts to trigger the webhook, including those that are repeated when a response is not returned during the 10 min time-out period.
  • Success responses: the number of successful responses.
  • Failure responses: the number of responses about failed processing.
  • Failures since last success: the number of failed responses returned after the last successful response.
  • Last event: the date and time of the last event.
  • Next trigger: the date and time when the webhook will be triggered again. This is used if the last response was unsuccessful, that is, the return code was different from 2xx.
  • Last success: the date and time of the last successful response. This field also contains a link to that response. On clicking the link, you will get a pop-up window with details of the last successful response.
  • Last failure: the date and time of the last failed response. This field also contains a link to that response. On clicking the link, you will get a pop-up window with details of the last failed response.

Some of the above parameters reflect statistics on failures. If the webhook handler does not respond during 5 min (an approximate value) or the response code is different from 2xx, the system triggers the webhook again until the response is successful or the number of requests exceeds a certain limit, after which Connect considers that the webhook is out of order. The interval between consequent requests is not less than 5 min and it increases with each request.

HTTP Settings

On the HTTP Settings tab, you can view and change the API call parameters:

  • Method: the HTTP method (GET or POST) in the API call. You can change it in the editor.
  • Endpoint URL: the endpoint URL of the API call. You can change it in the editor.
  • JWT secret: a secret string used to sign the JWT sent in the Authorization header as the bearer argument. You can perform the following operations with it:
    • View the full value by clicking the eye icon next to the hidden string.
    • Copy the secret value to the clipboard using the copy button next to the string.
    • Generate a new value in the editor.
  • Headers: optional custom headers that you can add to the API call. You can add, remove, or change headers in the editor.

Custom Data

If you use the HTTP POST method in the API calls that the webhook will use, you can add custom data on the Custom Data tab:

You can review and edit the custom data in the JSON format using the editor.

Is this page helpful?
Translate with Google
Copied to clipboard