WebHooks
Pages 11
Clone this wiki locally
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
- Create new role for API access
- Create new user and assign that role
- 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"
- Create api registration key for that user (https://online.planmill.com/YOURINSTANCE/api/registrations.jsp)
- Setup service that will listen for requests
- E.g. http://YOUR_SERVER/accountupdate
- 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.
- 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