What are webhooks?

Webhooks allow your application to receive real-time notifications from Optum Connections whenever certain events occur to which you have subscribed. Rather than polling the API for updates, webhooks enable Optum to “push” event data directly to your server, ensuring that your system stays in sync without the need for constant API requests.
Webhooks are particularly useful for handling events related to payment processing, document management, or status changes within Optum Connections. For example, you can configure a webhook to trigger when a payment is issued, a document is processed or a batch operation is completed.

How does it work?

1. Webhook endpoint creation: Before anything, it's important that you create your webhook endpoint where events will be received.
2. Subscribing to an event: Once your endpoint is created, you will need to subscribe to the events your application is interested in.
3. Event occurs: When an event of interest happens in Optum Connections (e.g., a payment is processed), the platform generates an event and sends a notification to your webhook endpoint).
4. Webhook notification: The event payload is sent as an HTTP Post request to your webhook URL, containing details about the subscribed event (e.g., Payment ID, status, timestamp).
5. Process the event: Your server receives the webhook and processes the event, such as updating your database, notifying users or triggering additional workflows.
6. Respond to webhook: Upon successfully processing the event, your server should respond with a 2xx HTTP status code to acknowledge receipt.

Setup

1. Identify the events you want to subscribe to

You can check the Types of events for the list of all event types and pick the events your application is interested in.

2. Subscribe to the event

To start receiving events via webhooks, you'll need to configure a webhook endpoint on your server and register it with Optum:

Set up your endpoint: Create a URL endpoint in your application to receive webhook events. This endpoint will listen for HTTP POST requests that contain event data.

• Example endpoint URL: https://yourdomain.com/optum/webook

Register the endpoint with Optum: Subscribe to events and register your webhook to any event your application needs to be notified about. Visit Subscribing to events for more info.

3. Handle the event on your server

Once you've subscribed to the needed events, you can move to the next step of Handling webhooks.

4. Respond to the event

Send a 2xx HTTP status code after receiving the event to acknowledge successful processing. Avoid performing heavy processing tasks synchronously in your webhook handler. Check the Responding to an event page for more info on how to handle the response to the event.