Hook Into Events

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 for the study hooks will be utilized. Proper permissions and settings for user roles will need to be set in order to access the hook configuration tab.  Here is a sample:

This email and password will be used to create a BASE 64 authentication string that will be used to authenticate with the hook. 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, the end user in TrialKit will see a ProtocolError display:

webhookformerror

 

For information about the API and common endpoints, read here.