Skip to main content

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 - 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​

TriggerEventDescription
Invitation Sentintegrated_appointment_updatedTriggered the first time a notification is sent about this invitation
Invitation Begunintegrated_appointment_updatedTriggered whenever a user begins an assessment
Invitation Completedintegrated_appointment_updatedTriggered 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​

FieldNameDescription
external_appointment_idExternal Appointment IdThe external identifier of the appointment this measurement is related to
external_patient_idExternal Patient IdThe external patient id of the patient being measured
appointment_idMirah Appointment IdThe internal Mirah appointment id being measured
patient_idMirah Patient IdThe internal Mirah patient id being measured
invitation_idInvitation IdThe id of the invitation/questionnaire response being filled out
invitation_statusInvitation StatusNew, opened, begun, sent, not_required, locked_out,complete, expired, before, partial, canceled, manually_canceled
invitation_user_IdCompleting User IdThe 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.