If you're already accustomed to using webhooks or HTTP callbacks, subscribing to our Event API will feel very familiar. As events occur within the Optum Connections, the Event API will send the event data to your API based on your subscriptions.

Subscriptions

A subscription represents an endpoint you'd like event data sent to, as well as its corresponding configuration.

Create a subscription

You can configure a single subscription to receive all event data, or you can have multiple subscriptions as needed, sending specific types of events directly to different parts of your system.

To create a new subscription, send a POST request to /v1/event-api/subscriptions with the following required configuration:

• URL (url): The URL to which you want event data sent. We will issue a POST request to this endpoint only after successfully completing a handshake protocol.
• Event Names (eventNames): The list of types of event names you'd like to receive. Check the Event Types pages for a list of all the available Events you can subscribe to.
• Auth Object (auth): An object that defines the preferred authentication method to secure your endpoint. Currently, only apiKey is supported. You pass an object with a key that stores the secret value your subscription will use for signing the contents of the event data. This is described in greater detail on the Authentication and Security page.

Example:

{
  "url": "https://example.com/api/v1/optum/webhook",
  "eventNames": [
    "user_created"
  ],
  "auth": {
    "apiKey": {
      "key": "test-key"
    }
  }
}

Update an existing subscription

There may be reasons you need to update your subscription, such as updating your callback URL to a new version or rotating your secret.

Send a PUT request to /v1/event-api/subscriptions/your-subscription-id, and your subscription will be updated immediately.

Important: If you are rotating secrets, be sure to accept your current secret and new secret for a short timeframe. This will ensure you don't accidentally discard messages we are sending you with your current secret while the rotation propagates from your system to ours.

Unsubscribing

If you no longer want to receive event notifications, issue a DELETE request to the /v1/event-api/subscriptions/{"your-subscription-id"} endpoint, and we will remove your subscription.