Top

Articles in this section

See more

Businessmap Webhooks

Avatar
Businessmap Help
  • Updated

The easiest way to integrate Businessmap with another system is being notified in real time when changes occur. That's the job of the webhooks available for each board in Businessmap.

1. How to set up Webhooks?

To set up a webhook, please do the following:

Go to the sidebar to the right of each board interface -> select the dotted icon (1) -> open the Board Webhooks configuration panel (2). 

In the panel that pops up, enter one or more URLs to be called by Businessmap when changes occur (1):

Once you save your webhook, a unique secret key is generated (2). You can use this key to filter unwanted traffic from unauthorized sources. 
Important: Make sure to store it in a safe place, as it will only show up once.

- If you want to temporarily disable a webhook, use the switch button on the right.

- If you want to delete a webhook, just remove the corresponding URL and Save it.

The supported events for triggering a webhook are:

  • "Card created"
  • "Card details changed"
  • "Card is discarded"
  • "Card is restored"
  • "Card moved"
  • "Card archived"
  • "Card is unarchived"
  • "Subtask created"
  • "Subtask updated"
  • "Subtask deleted"
  • "Comment created"
  • "Comment updated"
  • "Comment deleted"
  • "Board renamed"
  • "Board archived"
  • "Board unarchived"
  • "Board deleted"
  • "Board structure changed"

Here are some sample payloads for the different webhooks are listed below:

{
"company": "MyCompany",
"event": "Card created",
"board_id": 1,
"card_id": 2,
"user_id": 3
}

{
"company": "MyCompany",
"event": "Card details changed",
"board_id": 1,
"card_id": 2,
"user_id": 3
}

{
"company": "MyCompany",
"event": "Subtask created",
"board_id": 1,
"card_id": 2,
"user_id": 3,
"subtask_id": 3
}

{
"company": "MyCompany",
"event": "Comment created",
"board_id": 1,
"card_id": 2,
"user_id": 3,
"comment_id": 4
}

{
"company": "MyCompany",
"event": "Board renamed",
"board_id": 1,
"user_id": 3
}

..... 

Note: The Board Webhooks have to be configured per individual board.
Webhooks are triggered for every activity occurring on that board, where the payload contains only a piece of small key information for your end service as a trigger to get further processing.

The secret key for the webhooks is passed as x-kanbanize-secret header value in the POST request.

This one is mostly used for integrations and notification purposes.  

2. Call external Web-Services from Businessmap.
Use-case-specific Webhooks

We also have a more in-depth mechanism using the Business Rules to invoke an external web-service. With this approach, you could build a very detailed filter/scenario when the Webhook should be triggered.

For example, when a card is moved in "Ready for Review" and the color of the card is "Red" invoke my "https://mycompany.com/special_script" with a detailed payload containing the Title of the Card, Assignee, etc. 

Please, check the dedicated external web service article for more information on how to trigger Webhooks. 

Related articles