Webhooks | PLANTA Online-Hilfe

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

JSON

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

JSON

{
  "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 `raw`: unformatted (Default) `msteams`: optimized for Microsoft Teams notifications
`author`	Required	String	User which is used as author
`enabled`	Required	Boolean	De/activates the webhook configuration
`objects`	Optional		Contains objects to be watched
`ids`	Required	String	IDs of the objects to be watched For `type=global`, the ID `1` is used.
`type`	Required	`global, projects, boards, cards, lists, swimlanes, users`	Object type of the objects to be watched, can only contain one type Using `global`, all objects in the system can be watched
`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

Global

Parameter	Type	Description
`watchChildActivities`	`addProject`	Adding of a project
`watchChildActivities`	Further activities of child objects

Project

Parameter	Type	Description
`watchActivities`	`updateProjectTitle`	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
`watchChildActivities`	`createBoard`	Creating a board
	`importBoard`	Importing a board
	`copyBoard`	Copying a board
	`createBoardFromTemplate`	Creating a board from a template
	`moveBoardTarget`	Moving a board into the project
	`moveBoardSource`	Moving a board out of the project
	Further activities of child objects

Board

Parameter	Type	Description
`watchActivities`	`deleteBoard`	Deleting the board
	`removeBoardDescription`	Removing the board description
	`updateBoardDescription`	Changing the board description
	`updateBoardTitle`	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
	`copyList`	Copying a list
	`moveListSource`	Moving a list into the board
	`moveListTarget`	Moving a list out of the board
	`createCard`	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

List

Parameter	Type	Description
`watchActivities`	`l`	Archiving a list
	`restoredList`	Restoring a list
	`deleteList`	Deleting a list
	`renameList`	Renaming a list
`watchChildActivities`	Activities of child objects

Swimlane

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

Card

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
	`renameChecklist`	Renaming a checklist
	`renameChecklistItem`	Renaming a checklist item
	`addAttachment`	Adding an attachment
	`renameAttachment`	Renaming an attachment
	`removeAttachment`	Removing an attachment
	`updatedCloudAttachment`	Changing a OneDrive attachment