Handling webhooks

Once a webhook is configured, Optum Connections will send HTTP POST requests. to your endpoint whenever an event you're subscribed to occurs. Here's how to process and handle these webhooks effectively:

1. Parse the payload

Each webhook request body follows a standardized envelop format for all events. This format ensures that all events follow a standardized structure, making it easier to process and understand them.

Field	Description	Example
id	The identifier of the object the event is related to (e.g., batch id, payment id etc.)	45b93ecf-c718-4255-8485-10228f ca6713
source	The source of the event	https://example.com
specVersion	The version of the CloudEvent spec	1.0
type	The type of event	batch_created
dataContentType	Content type of the data	application/json
data	The payload of the event	dynamic JSON object
time	The date and time the event was created	2024-12-02T15:24:40. 6048459Z
causationId	The identifier of the event	134433a2-387d-48b8-9d7e-ddc7af8c705f

📘
Note
Please note that the Data field contains a dynamic JSON object, which can vary depending on the specific event being published

Example of envelop and payload:

{
    "id": "45b93ecf-c718-4255-8485-10228f ca6713",
    "source": "https://example.com",
    "specVersion": "1.0",
    "type": "payment_loading_requested",
    "dataContentType": "application/json",
    "data": {
        "type": "payment_loading_requested",
        "status": "Loading",
        "paymentNetwork": {
            "id": {
                "paymentId": "48dcb7d85a9ccac148c045814ac4e84f",
                "networkId": "48dcb7d863d4e2730430c80e7ce2d17d"
            },
            "applicationId": "OPTUMACH",
            "reason": "Enrolled",
            "documentUrl": null,
            "status": "NotLoaded",
            "distributionServices": [],
            "currentDistributionService": null
        },
        "amount": 100.00,
        "batchStartTime": "2024-08-08T18:31:57.3774568",
        "startTime": "2024-08-08T18:31:59.7569869"
    },
    "time": "2024-12-02T15:24:40. 6048459Z",
    "causationId": "134433a2-387d-48b8-9d7e-ddc7af8c705f"
}

2. Respond quickly:

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

3. Asynchronous processing:

For complex tasks, enqueue the event data to process asynchronously, which reduces response times and improves reliability.

4. Idempotency:

To avoid processing duplicate events, store and check each event ID. This ensures each event is processed only once.

Example of handling webhook payload in typescript

import express, { Request, Response } from 'express'

const app = express();
app.use(express.json());

app.post('/optum/webhook', (req: Request, res: Response){
    const event = req.body;
    const { id, payload: { type, accountId } } = event
    switch (type) {
        case "batch_created":
            // Handle batch created event
            console.log(`Handling batch created for batch ${id} ${accountId}`);
            break

        case "batch_completed":
            // handle batch completed event
            console.log(`handling batch completed for batch ${id} ${accountId}`);
            break
        default:
            console.log(`Unhandled event type ${type}`)
    }
    res.status(200).end(); // Acknowledge receipt
});

app.listen(3000, () => {
    console.log('Server is running on port 3000')
})