Using Webhooks
Webhooks allow you to trigger external services in response to events in MyDataHelps. When one such event occurs, the system will make a HTTP POST request to the URL configured in the webhook. The payload of the POST will contain details about the event, such as the event type and the participant that triggered it.
Webhook Example
One way to use webhooks is by leveraging Amazon Web Services (AWS). For example, you might implement some logic in an AWS Lambda that is triggered by the “Survey Submitted” webhook whenever a survey is completed. The workflow would be:
- A participant completes a survey in MyDataHelps.
- MyDataHelps triggers the configured webhook with information about the survey and participant.
- An AWS API Gateway receives the webhook activation at its endpoint.
- The API Gateway triggers an AWS Lambda to execute the desired action. This may utilize other AWS services, such as a database to store app-specific information. For more information about how to trigger Lambdas with webhooks, see the AWS Documentation.
You can also implement a webhook endpoint in your own web application. All it takes is an endpoint that the webhook can send a REST POST request to.
Webhook Events
The following MyDataHelps events can trigger webhooks. View each event for details about how the event is triggered and what data is included in the webhook request payload.
| Event |
Description |
| Survey Submitted |
This type of webhook can be activated when specific survey(s) are completed. |
| Schedule Triggered |
This type of webhook can be activated from within a project schedule, such as on participant enrollment. |
Setting Up a Webhook
To set up a webhook, open up your Project Settings screen and select the “Webhooks” section.
- Select “Add” to create a new webhook.
- Enter the webhook endpoint URL.
- Select the webhook event and (if applicable) a survey you want to trigger on. If you want the same webhook endpoint triggered for multiple surveys, you will need to create multiple webhooks.
- Select whether this webhook is “live” (used for your real project data) or “test” (used for testing). See more on testing webhooks in the next section.
- Click “Save” to save your webhook configuration.
Delete a webhook by clicking the trash icon.
Testing Webhooks
When a webhook is set to “Test” mode, a test button appears next to it. This lets you to test your webhook by making a POST request with sample data to your webhook endpoint when you click the “Send Sample” button.
You can switch a webhook between “Live” mode and “Test” mode at will, though it is suggested that you maintain separate endpoints for testing and your live project to avoid mingling test data with your real data.
Verifying Webhook Requests
MyDataHelps includes a signed JSON Web Token (JWT) in webhook requests so that you can verify that the event originated from the MyDataHelps servers.
The MyDataHelps JSON Web Keyset (JWKS) URL is https://designer.mydatahelps.org/apicore/webhooks/jwks and it contains all public keys that could be used to sign a webhook JWT. Most technology platforms have available libraries to verify a JWT against a known JWKS, but below are the steps that a validation library would perform:
- Read and decode the JWT bearer token from the
Authorization header, e.g. Authorization: Bearer *jwt value here*. Reject the request if it is missing.
- Get the public keys from the JWKS URL above, caching them according to the cache-control header received with the response.
- Select the key from the JWKS whose
kid matches the kid header attribute of the JWT, rejecting the request if no match is found.
- Verify the signature based on that key and its
alg value from the JWKS.
- Verify the other JWT attributes:
iss is the exact value https://rkstudio.careevolution.com/inv
aud is your webhook URL, minus any querystring parameters
exp has not passed, allowing for several minutes of clock skew
In addition to the standard JWT validation above, there are some custom checks that you might choose to add in your own code:
- Verify that
patient_id matches the ParticipantID in the request body.
- Protect against replay attacks. MyDataHelps will always send a unique
jti value with every webhook request.
- Validate that the
body_sha256_base64url value matches the request body. Compute SHA-256 over the raw request body bytes exactly as received, before any JSON parsing, then Base64url encode without padding.
Responding to Webhook Requests
MyDataHelps will retry failed webhook events an additional two times a few seconds later. If your endpoint responds with an error, it is important that the status code is 4xx or 5xx since the MyDataHelps system does not look at the returned body of 2xx response codes to check for embedded error messages. MyDataHelps also counts redirect response codes as failures, so it is important to specify the final URL that you want to receive the notification.