Webhooks are user-defined HTTP callbacks that are sent in response to an event's occurrence. Within MyDataHelps Designer, you may use a webhook to be notified of an event or to trigger a non-MyDataHelps action, possibly in your Clinical Trial Management System (CTMS). You may require a developer's assistance for using webhooks, specifically to set up your webhook URL to which the MyDataHelps will call.
Webhooks can be accessed from Project > Settings > Webhooks.
Table of Contents
Available Webhooks
The following webhooks are available in MyDataHelps Designer:
Survey Submitted
You can configure a webhook callback for when survey answers are submitted, specifying the applicable survey(s). Importantly, this webhook callback contains a participant's ID, so the callback will be participant-specific.
Visit our Developer Documentation for an overview of the Survey Submitted Webhook.
Scheduled
Webhook callbacks can be triggered by schedules:
- Navigate to your project's Settings > Webhooks.
- Add your webhook, selecting "Scheduled" as the type.
- Navigate to your project's Schedules.
- Create or edit your schedule, selecting "Add Webhook to Call" as an action.
Webhook Parameters
The following parameters are including in webhook callbacks.
All Webhooks
The following parameters are included in all webhook callbacks:
| Parameter | Description |
|---|---|
ParticipantIdentifier |
A unique identifier for the participant in this project. This can be set up via the invitation sent to the user, or will be auto-generated if the identifier was not specified in the invitation. |
ParticipantID |
The stable, automatically generated, internal system identifier for this participant. Universally unique identifier (UUID). |
ProjectID |
The stable, automatically generated, internal system identifier for this project. Universally unique identifier (UUID). |
PatientIdentifier |
Deprecated parameter; identical to ParticipantIdentifier. |
PatientID |
Deprecated parameter; identical to ParticipantID. |
EventType |
Either "SurveySubmitted" or "ScheduleTriggered". |
Survey Submitted Event Webhooks
A survey submitted webhook endpoint is invoked once each time a result is submitted for any of the associated surveys. The following parameters are included:
| Parameter | Description |
|---|---|
EventType |
Value is set to "SurveySubmitted". |
SurveyID |
The stable, automatically generated identifier of the survey. |
SurveyResultID |
The stable, automatically generated identifier of the survey result. |
TaskID |
The stable, automatically generated identifier of the task. |
SurveyName |
The unique identifying name of the survey. |
Schedule Triggered Webhooks
A schedule triggered webhook endpoint is invoked once each time the associated schedule is triggered for a participant. The following parameters are included:
| Parameter | Description |
|---|---|
EventType |
Value is set to "ScheduleTriggered". |
ScheduleID |
The stable, automatically generated identifier of the schedule. |
ScheduleName |
The unique identifying name of the schedule. |
Testing Webhooks
When your webhook is configured, you can test it by setting the Mode to "Test" and clicking "Send Sample." When invoking a webhook in test mode, dummy parameter values are sent which would not be available in the test context.
Once you are satisfied, be sure to to set the Mode to "Live."