AWS Builder Center

Builder Center

From AWS Health Event to Customer-Ready Update

From AWS Health Event to Customer-Ready Update

For independent software vendors on AWS, an incident is never a single conversation. Updates chain from AWS to you, to your customers, to their users. This post shows how to route AWS Health events through Amazon EventBridge, resolve them to specific affected accounts and tenants using the AWS Health API's organizational view, and run a least-privilege responder that drafts forwardable holding statements.

Series: Operating at Hyperscale (7 articles)

  1. 1
    An Operational Maturity Model for Operating at Hyperscale on AWS
  2. …
  3. 7
    From AWS Health Event to Customer-Ready Update This article

Sunaina Karve

Independent software vendors (ISVs) are infrastructure for the rest of the economy. Observability, data and AI platforms, developer tooling, security, and healthcare interoperability all run on a layer of multi-tenant SaaS, and when one of those platforms degrades, thousands of downstream businesses degrade with it. That makes how an ISV communicates during an incident a question of broad consequence, not just an internal operations detail.
And for an ISV, an incident is never a one-on-one conversation. Your customers are businesses, and behind each of them are their customers. So when an AWS-side event hits a service you build on, the notification lands on you first, through AWS Health, and whatever you say next becomes the raw material your customers use to update their own users. Often that message travels under a service level agreement (SLA) that chains across all three parties. Call this the three-party SLA relay: AWS notifies you, you notify your customers, and they notify their users, each link bound by its own commitments.
That changes what "good" looks like during an incident. Detecting the event isn't the finish line. The real job is to answer one question fast and precisely: which of my customers is affected, and what can they forward to their users? The output you are optimizing for is what I'll call a forwardable update: a statement your customer can pass down the relay with little or no editing, because it already speaks in terms of impact, scope, and next steps rather than AWS internals.
This post walks through how to wire AWS Health into that pipeline, using Amazon EventBridge, the AWS Health API, and a least-privilege responder, so that "we don't have a root cause yet" ships with a confirmed blast radius attached. Think of it as the concrete implementation of the Well-Architected guidance to define a customer communication plan for service-impacting events (OPS10-BP05 , and FSIOPS6  in the Financial Services Lens): those pages tell you to have a plan; this one shows how to build the signal-to-customer pipeline behind it.

Route AWS Health events on category, scope, and persona

Every AWS Health event arrives in EventBridge from the source aws.health with the detail type AWS Health Event. The interesting part is the detail payload (schema reference ), which carries the fields you route on:
  • eventTypeCategory: one of issue, accountNotification, investigation, or scheduledChange
  • eventScopeCode: ACCOUNT_SPECIFIC or PUBLIC
  • eventRegion: the impacted Region
  • affected entities (when present): each with an entityValue and a status
Your first move: catch operational issue events and send them straight into your incident pipeline, while matching narrowly enough that a routine maintenance notice doesn't page the on-call at 3 a.m. EventBridge supports a range of targets  for this, including AWS Lambda functions, Amazon SQS queues, Amazon SNS topics, Amazon Kinesis Data Streams, and built-in targets such as CloudWatch alarm actions, so a single issue event can fan out to your chat, paging, and ticketing systems automatically.
One trap worth planning around: eventScopeCode separates ACCOUNT_SPECIFIC events (local to your accounts, with affected-entity detail) from PUBLIC events (reported regional service issues that surface even if you don't use the service). Here's the catch. Public events are not delivered through AWS managed notifications in AWS User Notifications . To capture them, you must add an EventBridge rule or a user-configured notification, and public events can take up to an hour to start arriving after you create the rule. If your tooling relies only on managed notifications, you'll silently miss the broad regional events that often matter most to a multi-tenant platform.
AWS Health events also carry routing metadata  built for exactly this job:
  • actionability (ACTION_REQUIRED, ACTION_MAY_BE_REQUIRED, or INFORMATIONAL) tells you whether the event needs action.
  • personas (OPERATIONS, SECURITY, BILLING) is designed, in AWS's words, to route information to the appropriate teams.
Use them. Fan SECURITY-persona events to your security responder and BILLING events to the account team, rather than dumping everything into one channel. One nuance: pure service-issue events don't carry an actionability label, because whether recovery action is needed depends on your architecture, not AWS's.

AWS Health isn't your only signal, and sometimes not the fastest

Keep AWS Health as the backbone, but wire one more signal into the same pipeline because it changes what you can say. When an Availability Zone is impaired, Amazon Application Recovery Controller (ARC) can shift traffic away from it, and it emits events to the same EventBridge bus  from the source aws.arc-zonal-shift (detail types such as Autoshift In Progress and Autoshift Completed). You can even subscribe without enabling autoshift yourself, using autoshift observer notification , configured per Region. An Autoshift In Progress event is worth catching because it often reaches you before a Health event does and lets your customer update lead with recovery ("we detected single-AZ impact and traffic has already been shifted away") rather than with impact. The same applies to your own CloudWatch alarms (CloudWatch Alarm State Change events ): route whichever signal fires first into the responder, since the fastest one starts the clock.

Resolve which customers are affected with the AWS Health API

Detection tells you an event exists. Turning it into a forwardable, per-customer update means resolving that event down to your accounts and tenants.
For a multi-account platform, that's the organizational view  of the AWS Health API . It's available on a Business Support+, Enterprise Support, or Unified Operations plan. Call the Health API from an account without one and you'll get a SubscriptionRequiredException. (A single account's own EventBridge rules only receive that account's events; seeing across the whole fleet is exactly what organizational view adds.)
There's a one-time prerequisite: enable AWS Health to work with your organization by calling EnableHealthServiceAccessForOrganization  from your organization's management account. After that, given an event's ARN from the EventBridge payload, the Health API's organizational operations let you:
  1. List which accounts in your organization the event touches.
  2. Resolve the specific affected resources per account.
A practical constraint to design around: DescribeAffectedEntitiesForOrganization  accepts at most ten account-and-event filter pairs per request and paginates the rest, so batch your affected-account list rather than assuming a single call returns everything.
The final step is the one only an ISV can perform: map each affected AWS account (and, where you encode it, each affected entityValue) back to the business customer that occupies it. That tenant-to-account mapping is what converts an opaque event ARN into a plain sentence, "customers A, C, and F are affected; everyone else is fine," which is precisely what your customers need to decide what to tell their own users. It is also the step that most ISVs leave manual, and the one that most determines how fast a forwardable update can go out.
A useful rule of thumb: if you catch yourself cross-referencing an event ARN against a spreadsheet of accounts twice during one incident, that lookup should become the automated first step of your responder, not something a person does by hand while the clock runs.
The same Health and organizational-view building blocks are often used to build an internal dashboard (see the AWS Cloud Operations post on using Lambda and QuickSight for a Health events dashboard ). That gives your operators visibility; the pipeline here aims the same data at a different target, the outbound message your customers can forward.

Keep the responder on a least-privilege role

An automated responder that reads AWS Health and drafts a status update needs read-only telemetry access and nothing more.
Grant it only the AWS Health read and describe permissions it actually uses (the account-level describe operations for events, event details, and affected entities, plus the organizational describe operations) and stop there. Note that the AWS Health organizational operations don't support resource-level permissions , so you scope the responder by limiting it to those read-only actions rather than by resource ARN.
Any write action the responder performs, such as posting to your status page or opening an internal ticket, belongs on a separate, narrowly scoped role, following IAM least-privilege best practices . The responder should never be able to modify AWS Health configuration. Read-only telemetry plus the one scoped write action it genuinely needs is what makes it safe to run unattended.

Draft the forwardable update from the event, not from scratch

The worst time to compose customer-facing wording is at minute 20 of a Sev-1.
Because the EventBridge payload already contains the impacted Region, the start time, the event status, and a human-readable latest description, you can template a forwardable update and fill it in from those fields, scoped to the capabilities your customers consume, not to raw AWS service names.
A good forwardable update states four things, none of which depend on knowing the root cause:
  1. An acknowledgment in the customer's own terms.
  2. The scope: which customers are affected, and, just as importantly, which are not.
  3. The action underway.
  4. A committed next-update time.
That last one matters most in a relay, because your customer sets their users' expectations based on when they'll next hear from you. Same rule of thumb applies: if you send the same class of holding statement twice, template it and wire it to the alert, so the next incident starts with a draft instead of a blank page.

When the root cause is AWS: keep owning the message

An upstream AWS event is the moment it's tempting to point at AWS and wait. Resist it. Your customers experience your platform, not AWS's, so the goal is to keep communicating as the accountable party while AWS works the fix.
Own the experience in your customers' terms. Lead every update with impact and scope, not attribution. Say "this capability is degraded for customers A, C, and F; we've engaged AWS and are driving to resolution," rather than pointing at AWS. Cite the AWS origin only as a fact that sets expectations on timeline, never as a reason the problem is out of your hands.
Build fallback so your update can change. Invest ahead of time in cross-Region or multi-AZ recovery (zonal shift and autoshift, covered above) and, for your most critical capabilities, cross-Region or multi-provider failover. That investment is what lets your message shift from "we're waiting on AWS" to "we detected the impact and failed over." Make failover a first-class step in your responder rather than a manual scramble.
Let your support relationship add precision, not excuses. Engaging AWS Support  is part of the playbook, and it lets you say something more specific than "we've reported it." Open the case at the right severity right away (under-classifying is the most common reason a case moves slowly), and lean on whatever tier you carry: a designated Technical Account Manager on Enterprise Support, or a standing incident team with proactive, minutes-fast engagement on Unified Operations . The value for communication is a concrete line your customer can forward, such as "this is a critical-severity case, our AWS incident team is coordinating with the service team, and the workload is onboarded for proactive incident management," which reads as named accountability behind the fix rather than a ticket in a queue.

Get ahead of scheduled change

Not every signal is an incident. AWS Health scheduled-change events, including planned lifecycle events  such as end-of-support notifications and version upgrades, are designed to arrive with a minimum lead time of roughly 180 days for major changes and 90 days for minor ones, where possible. Their affected resources burn down from a PENDING to a RESOLVED status as you remediate. (Worth knowing: these status updates are applied periodically and can lag by up to 72 hours, and resource-status burndown isn't supported in the AWS GovCloud (US) and China Regions.)
For an ISV, that lead time is an opportunity, not a chore. Reaching out proactively with "we're handling an upcoming AWS change on your behalf; no action needed from you" is a trust-building message you can send with zero incident, and the burndown status lets you track remediation across your fleet as you go.

Close the loop after every incident

AWS Health events are viewable through the Dashboard and API for up to 90 days , so persist the event ARN, the resolved set of affected accounts, and your outbound updates into your own store as the incident runs. Don't rely on the event still being queryable months later.
After resolution, send a closing update that confirms resolution, verifies stability, and commits to a root-cause summary within a defined window. Then feed the finding back into a guardrail: a new EventBridge rule, a tighter tenant-to-account mapping, a cross-Region fallback, or an updated runbook. Because your customer will use your writeup to produce theirs, a clear, forwardable post-incident summary is where a well-handled incident compounds into more trust than existed before it.

Conclusion

For enterprise ISVs, incident communication is a pipeline, not a conversation: AWS Health at one end, your customers' customers at the other. The forwardable update is what travels that three-party SLA relay intact. Wire AWS Health into EventBridge so the clock starts at detection (adding faster signals like ARC zonal shift where they help), resolve events to affected accounts with the AWS Health API organizational view, keep the responder on a least-privilege role, and template forwardable updates that state who is affected and when the next update lands.
Do that consistently, and "we don't have a root cause yet" becomes a message your customers can pass down the chain with confidence, which is what protects the enterprises you serve, and the trust that keeps them as customers.

Further reading

Following two additional AWS Health API organizational operations are useful when you build the responder:
About the author: The author is an Enterprise Support Manager at AWS, supporting many of the leading independent software vendors that build their platforms on AWS. This vantage point across a portfolio of multi-tenant SaaS providers informs the generalized patterns described here; nothing in this post reflects any individual customer's confidential architecture or operations.
# cloud-operations# api# incident-response# support

Series: Operating at Hyperscale (7 articles)

  1. 1
    An Operational Maturity Model for Operating at Hyperscale on AWS
  2. …
  3. 7
    From AWS Health Event to Customer-Ready Update This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article