Webhooks
Information
- PLANTA pulse offers outgoing webhooks which users can use to register on certain objects and events in PLANTA pulse and receive updates about these activities.
- To do so, a webhook configuration can be added in PLANTA pulse which reacts when the defined events occur and sends information to the user.
- That way, users can, for example, be informed about all updates within a board or about all activities of a user.
Initial Setup
Enable webhooks
- In the Administration panel→ Settings tab → API Settings menu item, activate the Enable Webhooks checkbox.
- From now on, webhooks can be configured via the PLANTA pulse REST API.
- The Print webhook debug logs checkbox can be used to configure whether debug logs for webhooks are to be printed.
- Where the logs are printed depends on the logger configuration.
Configuration
Information
- In order to subscribe to certain events in PLANTA pulse, configurations for webhooks can be added.
- It is possible to watch one or several objects and/or their child objects (e.g. all cards within a board).
- Both all activities or only certain activities of the objects can be watched.
- Webhook configurations can be added via the PLANTA pulse REST API using
POST /api/webhooks
. - Alternatively, webhooks can also be created and edited in the Administration panel → Webhooks
Example: A webhook which watches for when a list is renamed and when new users are added to a card within the list
const webhookExample = {
"endpoint": "https://example.url", // URL
"title": "New Webhook",
"description": "Watching a list",
"language": "en",
"format": "raw",
"author": "username",
"enabled": true, // you can turn off the webhook
"objects": {
"ids": [
"jvNyPn3zThWwMBYR9", "...", // Object IDs to watch, no different types possible
],
"type": "lists" // Object type
},
"watchActivitiesEnabled": true,
"watchActivities": [ // define activities to watch, don't add this if you want to watch any update
"renameList" // only triggers when a list title is changed
],
"watchChildActivitiesEnabled": true, // you can also turn off the child spectator
"watchChildTypes": [
"cards" // multiple types are allowed here
],
"watchChildActivities": [
"joinMember", "moveCard" // special acitvities to watch
]
};
Create Webhook in the Administration Panel
Procedure
- Open the Administration panel → Webhooks.
- Click .
- Enter a Title for the webhook.
- If needed, enter a Description.
- Enter the Endpoint to which the webhook is supposed to send information.
- Select a Format.
- Generic: unformatted (Default)
- MS Teams: optimized for Microsoft Teams notifications
- Select the Type of the object to be watched.
- Enter the Object Id(s) of the objects to be watched.
- If several IDs are entered, they need to be separated using commas.
- Select whether the activities of the object are to be watched.
- In the Activities to Be Watched field, enter the activities to be watched.
- If nothing is entered, all activities of the object are watched.
- Select whether child elements are to be watched.
- If needed, specify which child elements are to be watched.
- If needed, specify which activities of the child elements are to be watched.
Parameter
{
"endpoint": "string",
"title": "string",
"description": "string",
"language": "string",
"format": "string",
"author": "string",
"enabled": true,
"objects": {
"ids": [
"string"
],
"type": "string"
},
"watchActivitiesEnabled": true,
"watchActivites": [
"string"
],
"watchChildTypes": [
"string"
],
"watchChildActivities": [
"string"
],
"watchChildActivitiesEnabled": false,
]
}
Parameter | Optional? | Possible Values | Description |
---|---|---|---|
endpoint | Required | String | URL of the webhook endpoint |
title | Required | String | Title of the webhook configuration |
description | Optional | String | Description of the webhook configuration |
language | Optional | de, en | Language in which notifications are sent (default= en ) |
format | Optional | raw, msteams | Format in which the webhook sends notifications Details
|
author | Required | String | User which is used as author |
enabled | Required | Boolean | De/activates the webhook configuration |
objects | Optional | Contains objects to be watched | |
| Required | String | IDs of the objects to be watched For |
| Required | global, projects, boards, cards, lists, swimlanes, users | Object type of the objects to be watched, can only contain one type Using |
watchActivitiesEnabled | Required | Boolean | Defines whether the activities of the object are to be watched |
watchActivities | Optional | String | Activities to be watched If nothing is defined, all activities are watched |
watchChildTypes | Optional | String | Child object types to be watched If nothing is defined, all child objects are watched |
watchChildActivities | Optional | String | Activities of child objects to be watched If nothing is defined, all activities are watched |
watchChildActivitiesEnabled | Optional | Boolean | Enables watching child activities |
Object Types
Object | Child objects |
---|---|
Global | Projects, Boards, Swimlanes, Lists, Cards, Checklists, Comments, Workloads, Attachments |
Projects | Boards, Swimlanes, Lists, Cards, Checklists, Comments, Workloads, Attachments |
Boards | Swimlanes, Lists, Cards, Checklists, Comments, Workloads, Attachments |
Swimlanes / Lists | Cards, Checklists, Comments, Workloads, Attachments |
Cards | Checklists, Comments, Workloads, Attachments |
Users |
Activity Types
Parameter | Type | Description |
---|---|---|
watchChildActivities | addProject | Adding of a project |
Further activities of child objects |
Parameter | Type | Description |
---|---|---|
|
| Changing the project title |
updateProjectDescription | Changing the project description | |
updateProjectProjectKey | Changing the project key | |
removeProjectDescription | Removing the project description | |
updateProjectDetails | Changing the detailed description of the project | |
removeProjectDetails | Removing the detailed description of the project | |
updateProjectStartDate | Changing the start date of the project | |
updateProjectDueDate | Changing the due date of the project | |
addProjectDueDate | Adding the due date of the project | |
addProjectStartDate | Adding the start date of the project | |
deleteProjectDueDate | Removing the due date of the project | |
deleteProjectStartDate | Removing the start date of the project | |
setProjectCustomField | Selecting the value of a custom field on the project | |
unsetProjectCustomField | Removing the value of a custom field on the project | |
assignProjectCustomField | Adding a custom field on the project | |
unassignProjectCustomField | Removing a custom field from the project | |
createCustomFieldDefinition | Creating a custom field in the project | |
updateCustomFieldDefinition | Changing a custom field in the project | |
deleteCustomFieldDefinition | Deleting a custom field in the project | |
|
| Creating a board |
| Importing a board | |
| Copying a board | |
| Creating a board from a template | |
| Moving a board into the project | |
moveBoardSource | Moving a board out of the project | |
Further activities of child objects |
Parameter | Type | Description |
---|---|---|
watchActivities | deleteBoard | Deleting the board |
removeBoardDescription | Removing the board description | |
updateBoardDescription | Changing the board description | |
| Changing the board title | |
changeBoardPermission | Changing the board visibility | |
addBoardStartDate | Adding the start date of the board | |
updateBoardStartDate | Changing the start date of the board | |
deleteBoardStartDate | Removing the start date of the board | |
addBoardDueDate | Adding the due date of the board | |
updateBoardDueDate | Changing the due date of the board | |
deleteBoardDueDate | Removing the due date of the board | |
addBoardMember | Adding board members | |
removeBoardMember | Removing board members | |
archivedBoard | Archiving a board | |
restoredBoard | Restoring a board | |
setBoardCustomField | Selecting the value of a custom field on the board | |
unsetBoardCustomField | Removing the value of a custom field on the board | |
assignBoardCustomField | Adding a custom field on the board | |
unassignBoardCustomField | Removing a custom field from the board | |
createCustomFieldDefinition | Creating a custom field on the board | |
updateCustomFieldDefinition | Changing a custom field on the board | |
deleteCustomFieldDefinition | Deleting a custom field from the board | |
watchChildActivities | linkBoard | Linking a board on the board |
linkCard | Linking a card on the board | |
deleteLinkBoard | Deleting a linked board | |
deleteLinkCard | Deleting a linked card | |
createSwimlane | Creating a swimlane | |
copySwimlane | Copying a swimlane | |
createList | Creating a list | |
importList | Importing a list | |
| Copying a list | |
| Moving a list into the board | |
moveListTarget | Moving a list out of the board | |
| Creating a card | |
importCard | Importing a card | |
copyCard | Copying a card | |
moveCardTarget | Moving a card into the board | |
moveCardSource | Moving a card out of the board | |
Further activities of child objects |
Parameter | Type | Description |
---|---|---|
watchActivities | l | Archiving a list |
restoredList | Restoring a list | |
| Deleting a list | |
| Renaming a list | |
watchChildActivities | Activities of child objects |
Parameter | Type | Description |
---|---|---|
watchActivities | archivedSwimlane | Archiving a swimlane |
restoredSwimlane | Restoring a swimlane | |
deleteSwimlane | Deleting a swimlane | |
renameSwimlane | Renaming a swimlane | |
watchChildActivities | Activities of child objects |
Parameter | Type | Description |
---|---|---|
watchActivities | archivedCard | Archiving a card |
restoredCard | Restoring a card | |
deleteCard | Deleting a card | |
moveCard | Moving a card within the board | |
setDueDate | Adding the due date of the card | |
setStartDate | Adding the start date of the card | |
unsetDueDate | Removing the due date of the card | |
unsetStartDate | Removing the start date of the card | |
updateDueDate | Changing the due date of the card | |
updateStartDate | Changing the start date of the card | |
addedLabel | Adding a label | |
removedLabel | Removing a label | |
updateCardTitle | Changing the card title | |
updateCardDescription | Changing the card description | |
removeCardDescription | Removing the card description | |
joinMember | Adding a card member | |
unjoinMember | Removing a card member | |
completedCard | Marking the card as "Completed" | |
reopenedCard | Removing the "Completed" status | |
setCardCustomField | Selecting the value of the custom field on the card | |
unsetCardCustomField | Removing the value of the custom field on the card | |
assignCardCustomField | Adding a custom field to the card | |
unassignCardCustomField | Removing the custom field from the card | |
voteAdd | Adding a vote for the "Voting" custom field | |
watchChildActivities | addChecklist | Adding a checklist |
addChecklistItem | Adding a checklist item | |
addComment | Adding a comment | |
addWorkload | Adding hours worked | |
setChecklistItemFinished | Marking a checklist item as "Completed" | |
unsetChecklistItemFinished | Removing the "Completed" status of a checklist item | |
removeChecklist | Removing a checklist | |
removeChecklistItem | Removing a checklist item | |
| Renaming a checklist | |
| Renaming a checklist item | |
addAttachment | Adding an attachment | |
renameAttachment | Renaming an attachment | |
removeAttachment | Removing an attachment | |
updatedCloudAttachment | Changing a OneDrive attachment |
-
Page: