1. What's a webhook for?

Webhook A webhook is a way of notifying a third-party application when an event defined in Project Monitor occurs. For example: you can trigger the creation of a SharePoint space when a new project is created in Project Monitor. See Webhook Webhooks memo

When an event occurs in Project Monitorthe webhook created in Project Monitor calls a Web Service defined in the third-party application. It is therefore necessary for the third-party application to define Web Services.

SOAP web services are not supported.

The webhook can transmit simple data (id, code or label) about the triggering object to the third-party application. This information is parameterized in the webhook and depends on the capabilities of the Web Service called.

If required, the third-party application can then query Project Monitor to find out more about the objects in the Project Monitor. The third-party application can then, in turn, call a web service from Project Monitor (see our web services memo on this subject).

In this way, the third-party application can monitor changes within the Project Monitor to synchronize its information or carry out specific processing following these changes.

• An event triggers an HTTP POST request to a URL configured on the third-party application.
• Triggering events :
• Creating, modifying and/or deleting a user
• Creating, modifying and/or deleting a project
• The HTTP request returns the id, code or label of the trigger object.

2. Setting up webhooks

2.1 Definition of a webhook

Go to settings : Administration >Advanced settings > Technical configuration > Webhook

A webhook is defined by :

• A event within Project Monitorfor example, a project modification,
• A URL to call in HTTP or HTTPS,
• The method expected by the third-party application (GET, POST...)
• Parameters passed in header, used for authentication, for example
• A BODY parameter for POST, PUT or PATCH methods
• One of two call modes:
• Synchronous Useraction in Project Monitor that triggers the event ends when the notification to the third-party application is completed.

If an error occurs when calling the third-party application, the error status code is displayed on the screen.

NOTE: In this mode, the performance of the Project Monitor are altered by the execution time of the third-party application's web service.

1. Synchronous execution in the transaction Error preventsaction in Project Monitor.
2. Synchronous executed outside the transaction: Theaction is executed even if the notification returns an error.
• Asynchronous action ends in Project Monitor and notification follows. If an error occurs during notification, it is visible only in the current commands and in the application log file. This is the recommended and default setting.

For example, if a user modifies a project property, Project Monitor calls the web service designated by the associated webhook.

If in synchronous mode, Project Monitor waits for the webservice to return before completing theaction and handing over to the user. If an error occurs and the call is made within the transaction, the property modification is cancelled, otherwise, if the call is made outside the transaction, the property modification is carried out anyway.

In asynchronous mode, the property is modified and the webservice is called afterwards, as a background task .

It is possible to deactivate a webhook. In this case, no call is executed following theaction in Project Monitor.

Example of a webhook definition :

Webhooks can be disabled in the properties file of the Project Monitor. Here are the two new parameters to be set:

#com.vc.mm.webhook.disabled=true / false

• The value "true" deactivates webhooks on Project Monitor
• The "false" value enables webhooks on Project Monitor (default value)

#com.vc.mm.webhook.exception=https://webhook.site

• If webhook deactivation is set to "true", then :
• All webhooks are disabled except those starting with (in our example) https://webhook.site
• From the Project Monitor a red banner is displayed "Only webhooks with URLs starting with https://webhook.site are active (after solving the formula)":

• By default, the property is empty, so there is no exception.

It is possible to test strings in webhook URLs via the following parameter in the properties file of Project Monitor :

com.vc.atlas.formula.env_pm=dev

• Example of URL in webhook definition :

https://'+(CONFIG.env_pm.equals('dev')?'webhook.site':'monServeurTest')+'/90cd2995-6d8c-4424-a7d5-edf451311819?id='+OBJET.ID

• If env_pm is equal to dev then the URL will be :
Copy

https://webhook.site/90cd2995-6d8c-4424-a7d5-edf451311819?id=332499

• If env_pm is not equal to dev then the URL will be :
Copy

https://monServeurTest/90cd2995-6d8c-4424-a7d5-edf451311819?id=332499

• If the customer has 2 platforms, "TEST" and "PROD", this parameter differentiates between "PROD" and "TEST" webhooks in a single URL.

2.2 Webhook events

The webhook is triggered by an event in Project Monitor.

This event is defined by an application object (Project, User) and an action (Create, Modify, Delete or All actions).

• An event has been added, defined by the phase application object and an action (Create, Modify, Delete or All actions).
• It is possible to filter on projects. If the filter is activated, the webhook will only be triggered on filtered projects. This filter can only be activated for phase and project objects.

In the table below, you can note which actions in the Project Monitor trigger webhook events:

Event	Creation Project Monitor	Modification Project Monitor	Delete Project Monitor
PROJECT/Creation	Notified
PROJECT/Modification		Notified	Notified
PROJECT/Deletion			Notified
PROJECT/All actions	Notified	Notified	Notified

Event	Creation Project Monitor	Modification Project Monitor	Delete Project Monitor
USER/Creation	Notified
USER /Modification		Notified
USER /Delete			Notified
USER /All actions	Notified	Notified	Notified

Event	Creation Project Monitor	Modification Project Monitor	Delete Project Monitor
PHASE	Notified
PHASE		Notified
PHASE			Notified
PHASE actions	Notified	Notified	Notified

Modification event

For a project, the following actions trigger the associated modification webhooks:

• Property modification (code, label, status, project manager, etc.)
• Modifying an attribute
• Modifying a structure link
• Team modification
• Modifying project links
• template modification

For a user, the following actions trigger the associated modification webhooks:

• Modification of a property (login, last name, first name, end date, etc.)
• Modifying a general role

For a phase , the following actions trigger the associated webhooks in modification :

• Property modification (name, code, start date, end date, etc.)
• Modifying an attribute
• Modification of dependency
• document modification

2.3 Setting up webhook data

It is possible to parameterize the url, body and headers with Project Monitor.

In this case, it is necessary to surround fixed parts with apostrophes and concatenate variables with the sign + as for calculated attributes or measures.

• Headers

Content-Type: application/json; charset=utf-8

project-id: OBJECT.ID

info : 'Modification'+OBJET.ID

• Body

‘{ idObjet :’+ OBJET.ID+ ‘}’

• URL

The URL will be constructed in the same way:

For example, the URL could take the following form:

https://application-tierce/url-web-service?id='+OBJET.ID

There are 4 types of variables:

• OBJECT: information on the object (Project, User, Phase) that triggered the notification (available properties: ID, CODE and LIBEL)
• UP_ATTRIBUT: a platform text attribute identified by its code.
• CONFIG transfer of a value defined in the Project Monitorfor example, a server name.
🚦

The CONFIG variable can only be used in On Premise installations, and is therefore not available in SaaS.

• OBJECT_ATTRIBUT: information on an attribute (Project and Phase) that triggered the notification (available property: code of theattribute searched for).
• Example: OBJECT_ATTRIBUT.CODE_ATTRIBUT

# Definition de l'ensemble des valeurs de configuration reprises dans les formules des webhook
# Une ligne par définition nom = valeur.
# Lorsque le nom apparaitra dans la formule, il sera remplacé par sa valeur
# com.vc.atlas.formule.<nom> = <valeur>
# depuis 6.1.4
# obligatoire : non

com.vc.atlas.formule.sharepoint=third-party-server

'https://’+CONFIG.sharepoint+’/url-web-service?id='+OBJET.ID

https://application-tierce/url-web-service?id=50123

2.4 Test function

On the webhook page, you can test the webhook by clicking on the cogwheel.

You can then select a project or user to simulate the event.

During a test launch, Project Monitor pre-register your webhook.

During the test, more information is sent to the user, including the results corresponding to the calculated values.

For your information, the http://webhook.site allows you to simulate a third-party application and receive calls made by Project Monitor. Of course, Virage Group does not support this site provided by: https://github.com/fredsted/webhook.site.

2.5 Error messages

On Project Monitor webhook error messages are generated as soon as a third-party application responds with an error status code greater than 299. The webhook response body, if any, is added to the error message from Project Monitor.

The error message is generic, with a variable part containing the webhook label, the status code and the error message . Example below:

"The webhook 'TEST' responded an error (status code:400) errormessage 19/3/18 17:19"

The "error message " corresponds to the response body of the third-party application.

Below is an example of the "error message " returned by the third-party application to Project Monitor :

• The "WEBHOOK_1" value corresponds to the Webhook "label" entered in the Project Monitor :

• status code "300" and error message can be defined in the third-party application:
• The format of the error message in the body is "free text, JSON format".