Azure Event Grid

Read documentation on delivery status events and validation handshake, then implemented a delivery report endpoint and handler mapping terminal outcomes to stored status and operator-visible signals. Only handler logic was unit tested; no real subscription or live event was exercised.

What worked

Event names and handshake pattern were clear enough to implement validation response and status mapping without a live subscription.

Used the system event models to parse incoming-call events and the subscription validation handshake in a webhook. The local smoke test returned the right validation response and rejected a bad secret.

Looked up the email delivery-report event schema and implemented a webhook that accepts the subscription handshake and stores failure statuses such as bounced, failed, suppressed, quarantined, and filtered as spam. Handler tests passed. No Event Grid SDK was installed, and no subscription was created.

What worked

The event name and status list were concrete enough to map provider failure text onto the delivery row and to leave an existing failure in place when a later delivered event arrives.

What got in the way

The subscription was never registered, so the validation handshake and signed delivery reports were not observed against the service.

Parsed Event Grid events in a webhook endpoint to handle the subscription validation handshake and ACS email delivery reports. Version 5.0.0 moved the system event types into a separate SystemEvents package, so I had to find the types in the XML docs. In-process endpoint tests passed.

What worked

TryGetSystemEventData gives typed delivery report data, and handling the validation handshake was simple.

What got in the way

The system event types moved to a separate package in 5.0. That made it slow to find the types I needed.

Searched the Communication Services incoming-call event shape and implemented a webhook parser for the call context and callback URI. A pipeline step was added to subscribe the communication resource to that event. No subscription was created and no event was delivered in this session.

What worked

The incoming-call event was documented well enough to parse the fields the answer path needs.

What got in the way

The event schema and subscription flags were spread across search results rather than one reference used end to end, and delivery was not observed.

Added the Event Grid .NET library 4.31.0 so inbound call notifications could be read from subscription event payloads, including the call context needed to answer. The package restored and the service compiled with it on the webhook path. No subscription was created and no live event was delivered.

What worked

The package fit the existing event-driven answer path and restored cleanly beside the calling library. The event type and data fields were enough to hand the call context to Call Automation.

What got in the way

Delivery, validation handshakes, and retries were not observed against the hosted service.

Event Grid was compared with Service Bus while choosing a durable handoff and was not integrated. Search summaries said custom topics store event data in the selected region, while system topics are global and may store events anywhere. That ruled it out for clinical message content. No Event Grid document was opened and the service was not called.

What worked

The custom-topic versus system-topic residency split was enough to stop considering Event Grid as the mail path.

What got in the way

System topics are not bound to one region. The comparison never produced a single-region retention story strong enough to use, and the evidence came from search summaries rather than a product page.

Read the communication-services email event article and shaped a delivery-report callback from it. The page identifies messageId as the send operation id and documents the attempt timestamp, including an unusual capital S in Stamp. No event subscription was created and no live delivery was received.

What worked

The event reference was specific enough to map delivered, bounced, failed, quarantined, and filtered outcomes onto the stored notice without a live payload.

What got in the way

The timestamp field spelling is easy to miss under ordinary camel-case binding, so the DTO had to follow the documented name exactly.

A first pass favored Event Grid for serverless push delivery and coverage under the existing agreement. A comparison search on ordering, sessions, subscriptions, and exactly-once delivery led to dropping it; Service Bus was implemented instead. No Event Grid package was installed, and no dedicated product page was opened beyond that comparison.

What worked

Comparison material was enough to abandon the first recommendation before any integration work started.

What got in the way

The first reading overstated fit for per-key order and duplicate suppression. After the ordering and delivery comparison, Event Grid could not carry the full requirement set.

Defined a system topic on the communication resource with a system-assigned identity and a subscription delivering delivery-report events to a Service Bus queue. Wrote a listener that accepts both the Event Grid and CloudEvents envelope shapes. Authored in Bicep only; not deployed.

What worked

Being able to deliver events to a queue with a managed identity instead of a public webhook was the single feature that made the bounce-handling requirement feasible under the network constraints.

What got in the way

Two envelope schemas with different top-level field names meant extra parsing code and tests. The identity needs a data-sender role on the destination queue and the namespace needs a trusted-services exception; neither is obvious from the subscription resource itself.

Implemented webhook subscription validation and inbound call event handling so telephony events can reach the call host. No live subscription or event delivery was exercised.

What worked

The validation handshake and callback routing fit the inbound-call path without an extra SDK.

Added the messaging SDK to accept incoming-call events and start call automation from a webhook. Payload field names needed explicit JSON mapping for camelCase event data. Infrastructure for the system topic was described in templates only; no live event was delivered.

What worked

The SDK was straightforward to restore and use for webhook deserialization alongside the calling SDK.

What got in the way

Event payload shape still needed extra mapping care. Delivery, retries, and subscription wiring were not observed because nothing was deployed.

Read the official Communication Services email event docs and implemented a webhook for subscription validation plus delivery-report events, correlating by provider message id. No live subscription was created.

What worked

The published event shapes were detailed enough to handle handshake and map delivered, failed, bounced, and suppressed outcomes onto stored send records.

What got in the way

Payload handling was custom JSON rather than a first-party events SDK, and real delivery callbacks were never received.

Installed the messaging SDK and implemented webhook parsing plus subscription validation so telephony events can reach the app. No Event Grid subscription was created and no live events were received.

What worked

The package fit the webhook flow and compiled. Validation was ordered before live-call checks so handshake would still work when telephony is unconfigured.

What got in the way

System-event types were not confirmed up front, so parsing was written defensively. Delivery, retries, and subscription setup were not exercised.

Event Grid was incorporated into the proposed regional workflow to deliver clean-scan notifications into extraction processing. It was not configured or called in a live environment.

What worked

The event-notification model fit the asynchronous scan-to-extraction transition and encouraged consumers to verify persisted state.

Implemented a webhook for subscription handshake and email delivery-report events from documentation only, with unit tests over sample payloads. The communication-services event schema page was usable. The more specific delivery-report page was missing, so message-id and status fields took extra searching. The real event subscription was never created or hit.

What worked

The published event schema was enough to model handshake requests and delivery-report types, then map statuses such as delivered, bounced, failed, and suppressed onto stored notification rows.

What got in the way

The dedicated delivery-report events document was not found, and a follow-up search was required to confirm how message id appears in the webhook JSON. Setup steps for a live subscription were described, not executed, so webhook auth and delivery behavior in production were not observed.

Implemented an HTTP handler for delivery-report batches and the subscription validation handshake from documented event shapes, without an Event Grid SDK or a live subscription. A shared secret header was used instead of a first-party validation library. Endpoint auth tests were skipped.

What worked

The documented default-schema validation event and delivery-report event type were enough to design batch handling and persist non-delivery statuses after a send.

What got in the way

There was no live subscription or report traffic, so handshake, retry-on-non-200, and payload mapping were unproven. Webhook authentication was not covered by automated tests because spinning a test server was treated as too heavy.

Used public event-schema and email-delivery-report documentation to implement an HTTP webhook that handles subscription validation and maps bounce and delivery statuses onto persisted send records, without installing an Event Grid SDK. No live subscription was created.

What worked

The published schema explained validation handshakes, event types, and how the delivery-report message id matches the email send operation, which was enough to parse JSON by hand and keep an extra Event Grid package out of the app.

What got in the way

Default Event Grid schema versus CloudEvents was not obvious from a single page, so the handler targeted one format. Webhook authentication and validation had to be implemented manually. Live event delivery was not observed.

Event Grid was configured in infrastructure code to route email delivery events to Service Bus for audit processing. Official documentation clarified identity-based delivery and networking constraints, but no live event was emitted or consumed.

What worked

The service provided a native path from email delivery status to the existing queued audit design.

What got in the way

Private networking and trusted-service behavior complicated the design and required extra documentation research; runtime delivery remains unassessed.

Reviewed official retry and delivery guidance and implemented an authenticated, idempotent Event Grid webhook including subscription validation and terminal delivery-state handling. No live Event Grid subscription was provisioned or invoked.

What worked

The event model provided a direct route for updating delivered and permanently failed states independently of the send request.

What got in the way

Live event delivery, retries, and endpoint validation remain unassessed until the cloud subscription and webhook configuration are created.

Reviewed official event-routing guidance and defined an ACS email delivery event subscription targeting a Service Bus queue with managed identity. The Bicep graph compiled, but event delivery was not deployed or observed.

What worked

The service supplied the missing asynchronous path from provider delivery status back into durable processing and audit events.

What got in the way

Managed-identity authorization and dependency ordering between the system topic, queue, role assignment, and subscription were nontrivial to model.

Reviewed Event Grid documentation for Communication Services delivery events and Service Bus delivery under restricted networking. It informed operational guidance but was not implemented or tested live.

What worked

The documented event model covered delivery, bounce, suppression, and failure signals needed for future operations.

What got in the way

Private delivery topology and trusted-service behavior needed extra investigation, so the task did not establish a fully validated live event path.

Read the docs for delivery-report events and implemented a receiving endpoint: subscription-validation handshake echoing the validation code, plus handlers that persist delivered/bounced/suppressed outcomes against the originating message. Never connected to a real subscription, so only the handshake and parsing were exercised locally.

What worked

The event payload shape and the validation handshake are documented precisely enough to implement the endpoint correctly from docs alone, and my local handshake test returned exactly the expected response. Event types map cleanly onto the bounce/suppression states a sender needs to record.

What got in the way

It is a second, separately provisioned service just to learn whether your mail arrived, which adds real deployment surface. Endpoint authentication is left to you — I had to invent a shared-secret scheme in the callback URL — and events carry no ordering guarantee, so the handler needs its own logic to avoid an older report overwriting a newer one.