The API serves as an excellent way for your third-party application to request specific data or to initiate changes to data in Cerbo. However, there are many scenarios where the application that you're building needs to know about events that happened in the EHR. For instance, if you want to send a special welcome email to each patient that registers with Cerbo, it's much easier if Cerbo sends your application a notification rather than requiring you to ask for a list of new patients very few minutes. These types of notifications are called "webhooks" and Cerbo allows you to easily configure these notices for a huge number of actions so that your application can know when specific types of data are added, modified, or removed within the EHR.
Webhooks can be configured by going to Admin > Manage > Integrations. Only users with Superadmin permissions can update webhooks. When you add a webhook endpoint, you must enter the URL and select each event that you would like to receive notifications for at that endpoint.
Some important notes about webhooks and their limitations:
- In order for your application to receive webhooks you must set up a "listener" that is accessible via the HTTPS protocol using a FQDN. The HTTPS protocol requirement ensures that data will remain secure in transit to your application, but it means that you must have a valid SSL certificate set up on your listening application.
- Webhooks contain PHI - please ensure that you have adequate security set up around your listening application and hosting environment, and that you're taking precautions when logging and storing incoming webhooks
- For security purposes you may want to add authorization headers to your webhooks. Our interface allows you to specify these headers, and we recommend doing this to avoid having malicious actors send fake webhook data to your application. Our webhooks do not create a sending hash that uniquely verifies each outbound webhook message, so please make sure to keep these authorization headers safe.
- If you want additional security on your webhooks, you can also choose to white-list your Cerbo build's IP address. This IP address will be mostly static (generally for years at a time), though it is worth noting that your Cerbo build may change IP addresses if we need to rebalance our infrastructure, so only employ this validation approach for non-critical webhooks.
- Webhooks are sent in real time. When a change is made in Cerbo the system will check if there is a configured webhook for that action and send out an immediate notification (there is no queuing engine, so there will be no delays other than network latency time)
- Because there is no queuing engine, we will not re-transmit webhooks that do not result in 200 response codes from the receiving application. This means that if your application is offline or having issues, you will not receive webhooks triggered during the outage period.
- While we do version our webhooks, we generally consider webhooks to be "triggers". You will see additional properties be added periodically, and the JSON data that is included is often more limited than what you would see from API responses. For instance, you'll often see that relational joins to other data types will be represented by numeric IDs rather than objects or string-names. As a result, we recommend that most webhooks be responded to by an API call to fetch the expanded object. This will be more reliable and the API is much more strictly versioned.
- Cerbo does offer a "delta" API endpoint that performs a similar function to webhooks, and can be very useful for cases where triggers are not time-sensitive, but webhooks are generally the easiest way to get notified of changes that occur within Cerbo.