Allowing Data to be Pushed Into TrialKit
Webhooks are used to tie into TrialKit when an event/workflow involves an external system that needs to be triggered from TrialKit.
WebHooks allow qualified programmers to extend the capabilities of the Trialkit application by initiating an external process from a TrialKit event. The possible events are:
- Save of a new record
- Update of an existing record
- Review level changes on a record
When an event is triggered, the configured webhook api route is called with a dictionary passed in the body. The data includes the record ID, form ID, and form Name. This JSON data can then be used outside of TrialKit in conjunction with the API library to retrieve additional desired form data.
Trialkit Hooks can be configured in the Study Configuration Settings page within the study that the hooks will be utilized.
User's role has access to Configure hooks
This is also possible on the iOS mobile app via the study status screen.
The email and password defined by the user will create a BASE 64 authentication string that will be used to authenticate with the hook URL. This is not required, but is suggested to prevent unauthorized data accessing the external URL.
Currently only Synchronous communication is supported. The hook will expect a response and prevent the user from moving on until a response is received or the timeout is reached.
Sample of JSON that will be sent to the hook for a new (insert) record:
{"trans_id":"436",
"form_id":"319",
"form_name":"Sample Form",
"OnInsert":true}
Sample of JSON that will be sent to the hook for an updated record:
{"trans_id":"435","form_id":"319","form_name":"Sample Form","OnUpdate":true}
Sample of JSON that will be sent to the hook for an review level change:
{"trans_id":"435",
"form_id":"319",
"form_name":"Sample Form",
"OnReview":true,
"wf_id":1,
"wf_object":
{"wf_id":1,
"wf_seq":1,
"wf_name":"Monitor Review",
"wf_role1":4,
"wf_role2":-1,
"wf_role3":-1,
"wf_fl":true,
"wf_lock":true,
"wf_sign":false,
"wf_soft":false,
"wf_status":10,
"wf_desc":"Monitor Review"},
"wf_status":10,"LockBroken":false}
If there is an error communicating with the external URL, the end user in TrialKit will see a Protocol Error display like below. The record within TrialKit will still save or update as applicable.
Once the external endpoint receives one of the notifications above, then the following endpoint could be called to get all the data for that transaction ID: form/7/<trans_id>
For information about the API and common endpoints, read here.