Respond to important events in near-real-time
Receiving webhook events is particularly useful for listening to asynchronous events such as creation/resolution of differences and discrepancies and changes to group status.
To start using webhooks, you’ll need to register the endpoints you want to use in the Command Center. After you register them, Noyo can push real-time event data to your application’s webhook endpoint as they happen. Noyo uses HTTPS to send webhook events to your app as a JSON payload.
Event name | Event key |
---|---|
Snapshot status changed | member_snapshot.status_change |
Snapshot Fulfillment Summary updated | member_snapshot_carrier_fulfillment_status.status_change |
Difference created | difference.created |
Difference marked as a discrepancy | difference.discrepancy |
Difference resolved | difference.resolved |
Difference replaced | difference.replaced |
Group Created | group.created |
Group Connection Request created | group_connection_request.created |
Group Connection Request status changed | group_connection_request.status_change |
Group Disconnection Request created | group_disconnection_request.created |
Group Disconnection Request status changed | group_disconnection_request.status_change |
The webhook HTTP payload will include information in both its HTTP headers and its request body. Event payloads do not contain any PII or PHI. Noyo recommends using the corresponding Get difference when you receive any .created
webhook.
The payload will be sent with the following HTTP headers:
Each webhook event contains the following fields in the response body:
Some events may include additional fields.
Our The Tracking API and its webhooks enable you to build field-level change tracking, so you have complete transparency from the time Noyo initially processes the member snapshot to when we confirm the change was made successfully by the carrier. You can also listen for unexpected data discrepancies that could interrupt coverage for your members.
Read more about fulfillment summary here.
For any snapshot sent to Noyo that contains changes, a difference.created
event will be sent almost instantly after the snapshot is initially processed. This means you can save individual tracking identifiers for all field-level changes that are in-process.
Note that discrepancies found during carrier syncs will also initiate a difference.created
event, so Noyo suggests calling Get difference to populate all relevant details of the difference, such as its source.
If we detect that a processing change has not been made by the carrier, or we find a data discrepancy during a sync, Noyo will send a difference.discrepancy
event.
In cases where an open difference is replaced by another, Noyo will send an event that you can use to replace the association in your system.
When a change is completed successfully by the carrier or a discrepancy is resolved (whether due to a subsequent snapshot, a sync, or a manual portal update, Noyo will send a difference.resolved
event.
You can create webhook subscriptions in Command Center by going to Developer > Webhooks and pressing “New subscription”.
secret
key. You should choose a random string of text with high entropy. You can use the webhook secret to limit incoming requests to only those originating from Noyo. You may optionally provide an API key name to assist in future key rotationYou can send a test request to any subscription through Command Center.
The payload will resemble the following:
New event types will be continuously added; it is up to you to decide which events you want to process and how, but your implementation of the event listener must be able to handle new event types without breaking.
We guarantee at-least-once delivery of events, meaning webhook endpoints may occasionally receive duplicate events. All event requests include an event ID, which may be used to deduplicate webhook events.
We do not guarantee delivery of events in the order they happen. You should also use the Noyo REST APIs to fetch any missing data.
Authenticate all requests to your webhook endpoint.
Noyo includes an HMAC signature with each outgoing webhook request in an x-noyo-signature
HTTP header. Endpoints should verify each request by: computing an expected HMAC signature for the payload and verifying that the value contained in the x-noyo-signature
header provided by the sender matches the expected signature. Read more.
In order to prevent unnecessary retries, we recommend receiving webhook events and processing them in separate processes. Upon receiving the event, you should immediately respond with a 200
indicating that the event was successfully delivered.
unhealthy
status
active