Skip to content

WebHooks

vijijustin edited this page Oct 3, 2019 · 15 revisions

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

{"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
You can’t perform that action at this time.