Skip to content

WebHooks

Jump to bottom
azuredevops-connection edited this page May 12, 2026 · 32 revisions

WebHooks

Flow Diagram of Planmill Webhooks

Planmill service could notify external servers when some change occured in data. This is done with webhooks.

For example, when some account is updated, planmill will send POST request to specified url, with payload about changed object.

Start using webhooks

  1. Create new role for API access
  2. Create new user and assign that role
  3. Add access to Power user (or new role that you created) to use hooks. HRM -> Users -> View user api key (Employeedirectory.Users view api key) If above access right is not added, you will get "401 Unauthorized"
  4. Create api registration key for that user (https://online.planmill.com/YOURINSTANCE/api/registrations.jsp)
  5. Setup service that will listen for requests
    • E.g. http://YOUR_SERVER/accountupdate
  6. Create hook with HTTP request
    • POST https://online.planmill.com/YOURINSTANCE/api/1.5/hooks
    • {"hook":"request.update", "url":"http://YOUR_SERVER/accountupdate", "eventUser":545, "eventProject" : 66}

      eventUser and eventProject is optional. "request.update" and "timereport.update" supported for these optional parameters.

  7. Change name of some account, and observe trigger in your service
    • POST {"hook":"request.update","url":"http://YOUR_SERVER/accountupdate","Id":123}

Technical details

List of currently supported webhooks

See API docs for currently supported webhooks.

JSON Schema of a triggered hook.

The payload data format follows the structure of “get single” calls of the respective endpoints, but all fields use string data types. Currently, the JSON Schema for a triggered hook covers absence, account, project, opportunity, task, and time report payloads, but does not yet include assignment, request, team or user payloads. Delete hooks do not always support payload, in case you need payload for some delete hooks currently not covered, contact PlanMill customer service.

Example of hook creation

POST https://online.planmill.com/YOURINSTANCE/api/1.5/hooks {"hook":"account.update", "url":"[http://YOUR_SERVER/accountupdate]"}

You may create url addresses to catch webhooks for testing purposes by following the guide here.

Code example.

Example of POST message to provided URL (Check the access from System.Hooks.Definitions.account before performing this action ,for example)

{"hook":"account.update","eventUser":50,"Id":1104}

Code example of listening for hook: https://github.com/planmill/api-data-helper/blob/master/src/main/java/com/planmill/api/datahelper/webhooks/WebHookListener.java

If your service return non 2xx HTTP status or service is not reachable, error will be logged for further investigation. Planmill don't provide access for these logs.

Event Item Type Description
project.add Project Subscribe to new project creation
project.update Project Subscribe to project updates
project.delete Project Subscribe to project delete
request.add Request Subscribe to new request creation
request.update Request Subscribe to request updates. eventUser and eventProject supported
request.delete Request Subscribe to request delete
account.add Account Subscribe to new account creation
account.update Account Subscribe to account updates
account.delete Account Subscribe to account delete
absence.add Absence Subscribe to absence add
absence.update Absence Subscribe to absence update
absence.delete Absence Subscribe to absence delete
absence.readyforacceptance Absence Subscribe to absence readyforacceptance
timereport.add Timereport Subscribe to timereport creation
timereport.readyforacceptance Timereport Subscribe to timereport readyforacceptance
timereport.update Timereport Subscribe to timereport updates. eventUser and eventProject supported
timereport.delete Timereport Subscribe to timereport delete
task.add Task Subscribe to new task creation
task.update Task Subscribe to task updates
task.delete Task Subscribe to task delete
team.add Team Subscribe to new team creation
team.update Team Subscribe to team updates
team.delete Team Subscribe to team delete
user.add User Subscribe to new user creation
user.update User Subscribe to user updates
user.delete User Subscribe to user delete
assignment.add Assignment Subscribe to new assignment creation
assignment.update Assignment Subscribe to assignment updates
assignment.delete Assignment Subscribe to assignment delete
Limitations :
  • By default only 10 hook triggers can be fired on one action at the max
  • payload exclusion list is possible for specific fields
  • payload can be excluded fully from hooks by custom configuration
  • Only "https" endpoints can be registered as triggering url.
  • Here eventUser, eventProject supported only for request.update and timereport.update

Clone this wiki locally