How to Use Web Hooks
Introduction
Mirah supports a set of web hooks that allow our customers to be notified when certain key events occur.
Note that the web hooks do not contain PHI, but only the identifiers required to fetch PHI in our system.
Maturity
The web hook system is currently in Beta. Changes may still be made to the system as it expands. Users will be given adequate notice of any changes required.
Requirements to Set Up
Please contact Mirah Support to start using the web hook system. You will need to provide:
- A URL you wish to be called when events occur
- A set of events to subscribe to. This is currently limited to integrated_appointment_updated.
- A pre-shared key, which should be a string of 16-32 characters.
This is supported for integration and production systems, but a separate key is recommended for each.
Triggers
| Trigger | Event | Description |
| Invitation Sent | integrated_appointment_updated | Triggered the first time a notification is sent about this invitation |
| Invitation Begun | integrated_appointment_updated | Triggered whenever a user begins an assessment |
| Invitation Completed | integrated_appointment_updated | Triggered whenever a user completes an assessment. |
Payload
curl --location --request GET 'https://example.com/incoming/webhook' \
--header 'Content-Type: application/json' \
--header 'X-Hook-Signature: sha1=XXXXX' \
--header 'X-Hook-Event: integrated_appointment_updated' \
--data '{
"external_appointment_id": XXXX,
"external_patient_id": XXXX,
"appointment_id": XXXX,
"patient_id": XXXX,
"invitation_id": XXXX,
"invitation_status": XXXX,
"invitation_user_id": XXXX,
}'
Invitation Payload
| Field | Name | Description |
| external_appointment_id | External Appointment Id | The external identifier of the appointment this measurement is related to |
| external_patient_id | External Patient Id | The external patient id of the patient being measured |
| appointment_id | Mirah Appointment Id | The internal Mirah appointment id being measured |
| patient_id | Mirah Patient Id | The internal Mirah patient id being measured |
| invitation_id | Invitation Id | The id of the invitation/questionnaire response being filled out |
| invitation_status | Invitation Status | New, opened, begun, sent, not_required, locked_out, complete, expired, before, partial, canceled, manually_canceled |
| invitation_user_Id | Completing User Id | The user completing the assessment |
Shared Key Digest
The hook contains a header with a SHA1 digest of the body of the message, calculated using the pre-shared key given above, of the form:
--header 'X-Hook-Signature: sha1=XXXXX'
This is calculated as following, in Ruby:
'sha1=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), key, payload_body)
Where key is the PSK, and payload_body is the entire body of the message.