Event Notifications

Payerbox can push FHIR resource events to subscribers as they happen — for example, notifying a downstream system the moment a prior-authorization decision is recorded on a ClaimResponse. Notifications are built on Aidbox's topic-based subscription engine: an AidboxSubscriptionTopic defines what fires, and a delivery sink defines where the event goes. Production deployments deliver through AidboxTopicDestination sinks — AWS SNS or a PAS-aware rest-hook — and that is the recommended path. A standard FHIR R4B Subscription is supported as a standards-based alternative for subscribers that want the plain FHIR subscription contract.

For the regulatory and workflow context of the events themselves, see PAS. For platform details beyond what this page covers, see FHIR Topic-Based Subscriptions in the Aidbox docs.

How it works

Every notification path shares the same trigger, then diverges on the sink:

When a CRUD operation matches a topic's trigger, Aidbox delivers a notification to every active sink bound to that topic. Delivery is asynchronous, so a slow or unavailable subscriber never blocks the originating FHIR write.

Define the subscription topic

Both paths start from the same topic. Declare what to notify on. trigger.fhirPathCriteria narrows the firing condition; omit it to fire on every interaction of the resource type. For Prior Auth, trigger on the ClaimResponse that carries the decision.

{
  "resourceType": "AidboxSubscriptionTopic",
  "id": "pas-claimresponse-status",
  "url": "http://prior-auth.example.org/SubscriptionTopic/pas-claimresponse-status",
  "status": "active",
  "description": "Notify when PAS ClaimResponses are created or updated",
  "trigger": [
    {"resource": "ClaimResponse", "fhirPathCriteria": "use = 'preauthorization'"}
  ]
}

Topic destinations (recommended)

Production deployments deliver events through AidboxTopicDestination sinks — a Payerbox extension provisioned per integration. A destination reuses the AidboxSubscriptionTopic trigger above but replaces the standard Subscription with an AidboxTopicDestination, and can optionally enrich the payload with the triggering resource's referenced resources (Claim, Patient, Coverage) so the consumer does not resolve them itself. Payerbox ships three custom destination kinds:

Two operational notes carry over from AidboxTopicDestination:

• Custom profiles must be whitelisted. The custom profiles are added to the AidboxTopicDestination allow-destinations constraint before any destination using them is created.
• Destinations are immutable. Aidbox rejects PUT/PATCH on an existing AidboxTopicDestination; to change a target (ARN, region, endpoint) delete and re-create it.

If your deployment uses this path, ask your Payerbox contact for the destination configuration reference.

Standard FHIR Subscriptions (alternative)

A subscriber can instead create a standard FHIR R4B Subscription bound to the topic — configured entirely through standard FHIR resources, with no Payerbox-specific destination kinds.

Create it with admin credentials, or provision it from an init-bundle (see Provisioning at deploy time). criteria is the topic's url, channel is a rest-hook pointing at your endpoint, and the R4B backport extensions select the payload content and an optional keep-alive heartbeat.

{
  "resourceType": "Subscription",
  "id": "pas-claimresponse-sub",
  "status": "requested",
  "reason": "Downstream PA decision notifications",
  "criteria": "http://prior-auth.example.org/SubscriptionTopic/pas-claimresponse-status",
  "channel": {
    "type": "rest-hook",
    "endpoint": "https://downstream.example.org/fhir/notifications",
    "payload": "application/fhir+json",
    "header": ["Authorization: Bearer <token>"]
  },
  "extension": [
    {
      "url": "http://hl7.org/fhir/StructureDefinition/backport-payload-content",
      "valueCode": "full-resource"
    },
    {
      "url": "http://hl7.org/fhir/StructureDefinition/backport-heartbeat-period",
      "valueUnsignedInt": 60
    }
  ]
}

A new Subscription starts in requested and delivers nothing until your endpoint answers Aidbox's handshake POST with a 2xx; repeated delivery failures deactivate it again.

Each delivery is a Bundle whose first entry is a SubscriptionStatus, followed by the triggering resource — for Prior Auth the ClaimResponse whose reviewAction extension conveys the decision (see PAS). A subscriber that needs the full referenced context (Claim, Patient, Coverage) resolves those references against the FHIR API, or uses a topic destination, which can ship them pre-resolved.

A subscriber that triggers on Claim instead finds the ClaimResponse id in the claim-response-reference extension Payerbox adds to the stored Claim (see Claim/$submit), so it correlates the pair without a separate lookup.

Provisioning at deploy time

In production these resources are created from an init-bundle rather than by hand, with environment-variable substitution for environment-specific values (endpoint URL, auth token). One ordering rule applies: a subscription topic must exist before any Subscription or AidboxTopicDestination that references its url.

Gotchas

• Handlers must be idempotent. At-least-once delivery can repeat an event. Deduplicate on the resource id and version, or guard with your own idempotency key.
• Updates re-fire. The topic fires on every interaction matching the criterion, including writes your own subscriber makes back into Aidbox. Avoid feedback loops when subscribing to a resource your downstream also updates.
• A subscription stuck in requested is not delivering. On the Subscription path this means the handshake never got a 2xx — check endpoint reachability, TLS, and auth headers.

Related