Articles in this section

Webhooks

  • Updated
Follow

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:

  1. Navigate to your project's Settings > Webhooks.
  2. Add your webhook, selecting "Scheduled" as the type.
    Webhook_Setup.png
  3. Navigate to your project's Schedules.
  4. Create or edit your schedule, selecting "Add Webhook to Call" as an action.
    Schedule_Setup.png

Webhook Parameters

The following parameters are included 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).
EventType Either "SurveySubmitted" or "ScheduleTriggered."
The following parameters are now only a part of legacy webhooks and do not apply to any newly created webhooks:
  • PatientIdentifier: Identical to ParticipantIdentifier.
  • PatientID: Identical to ParticipantID.

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.

Screen_Shot_2022-04-04_at_15.56.29.png

Once you are satisfied, be sure to to set the Mode to "Live."

Related articles