Missed events occur when webhook delivery fails to reach your endpoint or encounters an error. If the system is unable to deliver an event after 3 retry attempts, the event is marked as a missed event. Additionally, the backend implements a circuit breaker (Check this page for more info about circuit breakers). If the circuit breaker is triggered after 3 failed retries, your endpoint will stop receiving new events until the circuit is reopened. To reopen the circuit and resume receiving events, you must call a dedicated endpoint.

To ensure no data is lost, the system provides a way for you to track, retrieve, and acknowledge missed events.

What to do if you have missed events?

1. Retrieve missed events

• Use the endpoint below to fetch all missed events for a specific subscription.
• Review the event data and decide how to handle it.

Endpoint: GET /api/event-api/v1/subscriptions/{id}/missed-events.

• Where {id} represents the subscription ID.
• X-Optum-Tenant-Id\- You need to add a header value that specifies the application Tenant ID to use for the request.

Response: A list with all the missed events.

Example:

[
  {
    "id": "9bcbc2d8-89c8-436b-9358-3489af0f0cb5",
    "eventName": "user_created",
    "subscriptionId": "ca6c9eb5-2af1-4e50-bacb-025beab96ca9",
    "eventPayload": "{\"firstName\":\"Bob\",\"lastName\":\"Smith\",\"email\":\"[email protected]\",\"type\":\"user_created\"}",
    "failurePayload": "Http error: StatusCode: 400, Message: {\"type\":\"https://tools.ietf.org/html/rfc9110#section-15.5.1\",\"title\":\"Bad Request\",\"status\":400,\"traceId\":\"00-32f50eca68e968060e2cf6ae1a8b9455-ce95653c673eef95-00\"}"
  },
  {
    "id": "42bcdc1f-e643-4127-b378-4565147d1214",
    "eventName": "user_created",
    "subscriptionId": "ca6c9eb5-2af1-4e50-bacb-025beab96ca9",
    "eventPayload": "{\"firstName\":\"Bob\",\"lastName\":\"Smith\",\"email\":\"[email protected]\",\"type\":\"user_created\"}",
    "failurePayload": "Http error: StatusCode: 400, Message: {\"type\":\"https://tools.ietf.org/html/rfc9110#section-15.5.1\",\"title\":\"Bad Request\",\"status\":400,\"traceId\":\"00-b9ae32cd18d8557e5aab697c3f0878e7-470c45c4b2bef032-00\"}"
  }
]

2. Acknowledge receipt of a missed event

Once you have processed a missed event, acknowledge it to remove it from the system.

Endpoint: DELETE /api/event-api/v1/subscriptions/{subscriptionId}/missed-events/{id}

• {id} represents the event ID.
• {subscriptionId} - represents the subscription ID.
• X-Optum-Tenant-Id\- You need to add a header value that specifies the application Tenant ID to use for the request.

Response: OK - HTTP Status 204

3. Reopen the circuit breaker

If your endpoint has stopped receiving events due to the circuit breaker being triggered, use the endpoint below to reopen it and resume event delivery.

Endpoint: POST /api/event-api/v1/subscriptions/{id}/circuit-breaker-close

• Where {id} represents the subscription ID.
• X-Optum-Tenant-Id\- You need to add a header value that specifies the application Tenant ID to use for the request.

Response: OK - HTTP Status 204

Key points

• Fetch missed events regularly to ensure you process all webhook data.
• Acknowledge events only after they are successfully handled.
• The system will not resend missed events, so you must manage them manually once retrieved.
• If your endpoint stops receiving events due to the circuit breaker, make sure to resolve the issue and reopen the circuit to continue receiving events.