(Example) Create a Webhook and Receive Notifications

Prerequisites

• AgilePoint NX OnDemand (public cloud), or AgilePoint NX PrivateCloud or AgilePoint NX OnPremises v7.0 Software Update 2 or higher.

Good to Know

• This example topic uses a simple example for webhook based on this use case:

  Faybey, a fictitious online fashion retailer, uses the Sales Invoice app to create and manage customer invoices. The company has problems with sales invoices that are not correctly executed. The CEO of Faybey wants to monitor the Sales Invoice app to find where the problems occur. The AgilePoint NX administrator creates a webhook to monitor possible problems in the Sales Invoice app. When an error occurs, the webhook sends a notification that the administrator can monitor.

• This example uses the Sales Invoice app from the AgilePoint NX App Store.

  For more information, refer to How to Get the App

  ​
• This example topic uses the third-party web site https://webhook.site for example purposes. This is a free, open source app you can use to test webhooks and other types of HTTP/HTTPS requests. In a production environment, use an app that is appropriate for your business requirements.

First, get the webhook notification URL from https://webhook.site.

Good to Know

• This example uses https://webhook.site to get the webhook notification URL that is required to create a webhook in AgilePoint NX. In a production environment, use a webhook notification URL that is associated with your webhook notification system.

How to Start

1. In a web browser, go to https://webhook.site.

Procedure

1. On the Webhook.site screen, to copy the webhook notification URL, click Copy.

   
   
   

Next, create a webhook in AgilePoint NX.

Prerequisites

• Get the webhook notification URL.

Good to Know

• This example shows how to create a webhook related to a process instance suspended event. You can also create a webhook related to other runtime events and security events such as role, group, and delegation.

How to Start

1. In the Manage Center, click System > Webhooks.

Procedure

1. On the Webhooks screen, click Create a Webhook.

   
   
   

2. On the Add Webhook screen, in the Name field, enter Sales Invoice App Errors.

   
   
   

3. In the Webhook Notification URL field, enter https://webhook.site/a85258a1-9371-4ed6-a43e-91a7a32a07cd.

   This is the example URL from webhook.site in Step 1: Get the Webhook Notification URL. In a production app, use the webhook notification URL for your business requirements.

   
   
   

4. In the Description field, enter Sends a notification when the Sales Invoice app has an error.

   
   
   

5. In the Type of Event field, select Workflow/Instance Based.

   
   
   

6. In the Select Event section, select Process Instance Suspended.

   
   
   

7. In the Application field, select Sales Invoice from the list.

   
   
   

8. Click Add Webhook.

Next, view a webhook notification when a configured event occurs.

Prerequisites

• In this example, the webhook is configured to send a notification when a process instance is suspended for the Sales Invoice app. For this event to occur, the Sales Invoice app must be configured for the use case, started, and have one or more running process instances. When one of the process instances is suspended — for example, because of an error — it causes the webhook to send a notification.

  In a production environment, a webhook notification is sent when the configured event occurs.

Good to Know

• This example uses https://webhook.site to view the webhook notification.

How to Start

1. In a web browser, go to https://webhook.site.

Procedure

1. On the Webhook.site screen, in the left pane, click the webhook notification.

   
   
   

2. Select Format JSON.

   
   
   

   This page shows the webhook notification in JSON format.

   
   
   

Next, change a webhook notification from JSON format to user readable format.

Good to Know

• This example uses http://json2html.varunmalhotra.xyz/ to parse the JSON webhook notification response. This is a freely available open source tool you can use to view the JSON message in a human-readable format.

  In a production environment, use an JSON parsing tool that is appropriate for your business requirements.

How to Start

1. In one web browser tab, open the webhook notification you received in https://webhook.site.

   For more information, refer to View a Webhook Notification.

2. In a different web browser tab, go to http://json2html.varunmalhotra.xyz/.

Procedure

1. In Webhook.site, copy the webhook notification in JSON format.

   
   
   

2. Go to http://json2html.varunmalhotra.xyz/.
3. On the Input Valid Jason field, paste the webhook notification in JSON format.

   
   
   

4. Click Send.

   
   
   

   The results page shows the webhook notification in a tabular format. In this example, the webhook notification shows information such as the cause of the notification (SuspendProcessInstance), the process instance name and ID, and the date and time the event occurred.

   
   
   

Prerequisites

• AgilePoint NX OnDemand (public cloud), or AgilePoint NX PrivateCloud or AgilePoint NX OnPremises v7.0 or higher.

Good to Know

• This procedure is optional. It is provided so you can test the example with an out-of-the-box app.
• This is part of the Background and Setup procedures, but many users preferred this step to appear after the example, not before it.

Procedure

1. Click App Store .

   
   
   

2. In the CATEGORY section, click Sales.

   
   
   

3. Click the Sales Invoice app.

   
   
   

4. On the Sales Invoice screen, click Add.

   
   
   

5. On the Trust App screen, click Trust it.
6. Click Return to site.