Webhooks

In this guide, we will look at how to register and consume webhooks to integrate your app with Avon. With webhooks, your app can know when something happens in Avon, such as someone sending a message or adding a patient.

Registering webhooks

To register a new webhook, you'll need to send your Avon contact an endpoint that Avon can call when an event happens. Also let your Avon contact know which of the event types you want to listen for.

Now, whenever something of interest happens in the EMR or patient portal, a webhook is fired off by Avon. In the next section, we'll look at how to consume webhooks.

Consuming webhooks

When your app receives a webhook request from Avon, check the event attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a conversation, message, etc.

Example webhook payload

{
  "event": "patient.created",
  "created_at": 1653798303000,
  "object": {
    "id": "user_Z1zXZKvqrpwxbznuW6lJ"
    // ...
  }
}

In the example above, a patient was created, and the object type is a patient.


Event types

  • Name
    patient.created
    Type
    Description

    A new patient was created.

  • Name
    patient.updated
    Type
    Description

    A patient was updated.

  • Name
    message.created
    Type
    Description

    A new message was created.

  • Name
    message.deleted
    Type
    Description

    A message was deleted.

  • Name
    appointment.created
    Type
    Description

    A new appointment was created.

  • Name
    appointment.started
    Type
    Description

    An appointment was started.

  • Name
    appointment.completed
    Type
    Description

    An appointment was completed.

  • Name
    appointment.cancelled
    Type
    Description

    An appointment was cancelled.

  • Name
    appointment.rescheduled
    Type
    Description

    An appointment was rescheduled.

Example payload

{
  "event": "patient.created",
  "created_at": 1653798303000,
  "object": {
    "id": "user_Z1zXZKvqrpwxbznuW6lJ",
    "object": "patient",
    "mrn": "8942726",
    "first_name": "Sally",
    "middle_name": "",
    "last_name": "Chen",
    "gender": "Female",
    "email": "sally@demo.com",
    "phone": "(408)872-5892",
    "date_of_birth": {
        "year": 1980,
        "month": 1,
        "day": 1
    },
    "ssn": "765876575",
    "caregiver": "user_X90XZKvqrpwxbznuW6lJ",
    "caregiver_only": false,
    "medical_centers": [
        "mctr_XbvBirnEb1Mli1OLwqnM"
    ],
    "addresses": [{
        "nickname": "Home",
        "line1": "60 W Main St",
        "city": "Avon",
        "state": "CT",
        "postal_code": "06001",
        "country": "US",
        "special_instructions": "Has a loud dog"
    }],
    "timezone": "America/New_York",
    "status_history": [
        {
            "status": "active",
            "changed_by": "user_Z1zXZKvqrpwxbznuW6lJ",
            "changed_at": 1653798303000
        }
    ],
    "custom_data": [{
        "key": "cfld_FZR6ioEDTkHKn62oknLF",
        "value": "Routine Care"
    }],
    "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
    "created_at": 1653798303000,
    "last_updated_at": 1653798303000
  }
}

Security

To know for sure that a webhook was, in fact, sent by Avon instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named avon-signature, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app:

Verifying a request

const signature = req.headers['avon-signature']
const hash = crypto.createHmac('sha256', {{webhook_secret_key}}).update(payload).digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

If your generated signature matches the avon-signature header, you can be sure that the request was truly coming from Avon. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Avon. Don't commit your secret webhook key to GitHub!