WebHooks

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/hook
   • {"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

Code example of creating webhook:

List of currently supported webhooks

See API docs for currently supported webhooks: https://developers.planmill.com/api/#hooks

Example of hook creation

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

Code example: https://github.com/planmill/api-data-helper/blob/master/src/test/java/com/planmill/api/datahelper/test/WebHooks.java

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
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