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.
- Synchronous execution in the transaction Error preventsaction in
Project Monitor.
- 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.
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.
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 todev
then the URL will be : - If
env_pm
is not equal todev
then the URL will be : - If the customer has 2 platforms, "TEST" and "PROD", this parameter differentiates between "PROD" and "TEST" webhooks in a single URL.
https://webhook.site/90cd2995-6d8c-4424-a7d5-edf451311819?id=332499
https://monServeurTest/90cd2995-6d8c-4424-a7d5-edf451311819?id=332499
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 | Modification | Delete |
PROJECT/Creation | Notified | ||
PROJECT/Modification | Notified | Notified | |
PROJECT/Deletion | Notified | ||
PROJECT/All actions | Notified | Notified | Notified |
Event | Creation | Modification | Delete |
USER/Creation | Notified | ||
USER /Modification | Notified | ||
USER /Delete | Notified | ||
USER /All actions | Notified | Notified | Notified |
Event | Creation | Modification | Delete |
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
In the Headers field, you must specify one header per line. A line is in the form <nom header> :<valeur header>
. The header value can contain :
but not the header name (the front part :
).
For example, header without variable part:
Content-Type: application/json; charset=utf-8
Example with a variable part (object.id) :
project-id: OBJECT.ID
or
info : 'Modification'+OBJET.ID
- Body
In the Body field, you specify a string that can be formatted in JSON, for example, as long as you respect the concatenation rule for fixed and variable parts, such as :
‘{ 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.
- 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
The CONFIG variable can only be used in On Premise installations, and is therefore not available in SaaS.
The 'CONFIG' variable (not available in SaaS)
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".