Webhooks

Overview

A webhook is a user-defined HTTPS callback. An API user account can be configured with one or more HTTPS URLs for a set of predefined events. When an event occurs, JSON information about that event will be POSTed with a Content-Type of application/json to the corresponding webhook URL, along with a signature header to allow the webhook to validate the POST.

The webhook URL should return a successful HTTP status code. Any data returned is ignored, so no data can be returned along with a status code of 204 No Content.

Webhook URLs will be requested from source IP addresses 54.213.162.103 or 54.213.10.26 in Cureatr’s live environment, and from 54.213.149.201 in the play (testing) environment.

Webhook Types

There are currently four types of webhooks.

Message Sent

This webhook is invoked when a new message is posted to a thread that was created by the API user that contains this webhook. Sample POST contents:

{
    "event": "message_sent",
    "time_sent": "2015-04-07T05:46:17.510801",
    "thread_id": "55198cb351c356a2de0603bf",
    "message_id": "55198cb351c356a2de0603ae",
    "user_id": "55236f2951c356c8d0e5901a"
}

Message Read

This webhook is invoked when a message is read in a thread that was created by the API user that contains this webhook. Sample POST contents:

{
    "event": "message_read",
    "time_read": "2015-04-07T05:46:17.510801",
    "thread_id": "55198cb351c356a2de0603bf",
    "message_id": "55198cb351c356a2de0603ae",
    "user_id": "55236f2951c356c8d0e5901a"
}

User Provisioning

This webhook is invoked when a user is created, locked, or unlocked, and an API user that contains this webhook has permission to communicate to that user.

Action “added” is used when user is initially provisioned or unlocked, action “removed” is used when the user is locked.

Sample POST contents:

{
    "event": "user_provisioning",
    "action": "added",
    "time_event": "2015-04-07T05:46:17.510801",
    "user_id": "joseph.mayer@mountsinai.org",
    "primary_ou": "msh",
    "user_pager": "8081234567"
}

User Status

This webhook is invoked when a user changes their status, and an API user that contains this webhook has permission to communicate to that user. Sample POST contents:

{
    "event": "user_status",
    "time_status": "2015-04-07T05:46:17.510801",
    "user_id": "55236f2951c356c8d0e5901a",
    "status": "off",
    "message": "away from my stethoscope",
    "user_pager": "7325551212",
    "covering_user_id": "55236f2951c356c8d0e5901a",
    "covering_user_pager": "6465551212"
}

Signature Verification

The webhook can verify that it has received a legitimate POST by verifying the signature sent in the X-Signature HTTP header.

To verify the signature, SHA256 HMAC the JSON body of the POST using the API users api key as the secret - and BASE64 encode the result. In pseudocode base64(hmac_sha256(api_key, body)). If this signature matches the one sent in the X-Signature header then the request is valid.

This site has a number of implementations of the above in various languages.

Here are some sample webhook implementations, demonstrating signature verification: