Configure your application for webhooks

Confirm receipt

When an event occurs, we start by making a request to your endpoint with an empty body. Configure your application to respond with either an HTTP 200 or HTTP 201 response that includes your secret challenge token in the message body. This way, we know it was truly your server that received the response.

HTTP 200 OK
Content-type: application/json
{ "challenge": "your-secret-challenge-token" }

If we receive a response within 2 seconds, we’ll call your endpoint again, but this time we'll include the event payload. Please respond again with your challenge token so we know you’ve received the event information.

If for some reason your endpoint isn’t accessible, we retry the notification up to 6 times with exponential backoff. Each event has its own unique delivery id and event id that you can keep track of. Read more in Missed and repeated webhooks

tip

In the event that your endpoint is down for a while, you can build a manually triggerable action to query our List all webhooks API. You can filter for a specific date range, event id, or for messages that couldn’t be delivered. Be aware that only 30 days of history is kept.

Webhook events from multiple clinics

If you’re writing software that will be used by multiple customers, it’s likely that they will each have their own Fullscript clinic.

For example, imagine your software is used by three of your customers, each with their own Fullscript clinic. When you get an event from Fullscript, how will you know which of those customers triggered it? Does it matter?

Diagram of an application that has three customers, each with their own Fullscript accounts. When an event is triggered, it's sent to the application, but a question mark asks which customer this event is for.

The answer is yes, it usually matters which of your customers triggered the event. Unless the event is product-related, you need to make sure you’re updating the right customer’s patients and treatment plans. (You may choose to keep a single list of Fullscript products in your database, but elements that are particular to your customers should be stored independently from each other.)

When you receive a webhook event, find the clinic_id in the event_payload. This identifies the clinic that triggered the event.

 ...
     "event_payload": {
        "event": {
          "id": "x5xxxxx8-92x7-4xxx-9x0x-345x404x94x1",
          "type": "patient.updated",
          "created_at": "2018-10-16T04:00:00.000Z",
          "clinic_id": "xx7x357x-9x36-xxxx-x553-7x3xx398xxx",
          "data": {
 ...