apointoo.
Request access
HIPAA

AWS SQS Outbox Design for Reliable Offline Conversions

cmsapointoo··8 min read

Short answer: A reliable offline-conversion outbox should commit a minimum generic event to an internal queue, retry safely, deduplicate by an internal event key, quarantine failures, and keep the external upload gate disabled until tenant-specific legal approval exists. As of 2026-08-15, AWS publishes SQS pricing, eligible-service scope, and Google Ads API upload guidance. None authorizes sending health-related identifiers or service details to an advertising platform.

AWS service fit and regional boundary

SQS is a delivery mechanism, not a permission to disclose data. AWS SQS pricing describes queue requests, and the AWS HIPAA eligible services reference supports a bounded provider-scope review. Google Ads API documentation describes offline-conversion upload fields and lifecycle. The safe architecture keeps the internal outbox separate from any outbound advertising action and records an explicit approval state.

Define the data boundary first. The source system records an approved generic outcome. The outbox stores only the fields needed to reconcile and retry that outcome. The worker reads the event, checks tenant approval, validates the payload, and stops if the gate is absent. A disabled external destination should be a normal state, not an exception handled by a human after data has already left the system.

Keep queue, dead-letter, logs, backups, keys, and workers in the approved region. A message that is safe for an internal queue may still be sensitive context if it contains a booking identifier or campaign relationship. Do not send patient names, email addresses, phone numbers, hashed identifiers, service names, treatment details, or clinical text to Google Ads.

Stage Allowed content Gate
Source transaction Customer-approved booking outcome and internal record Tenant authorization
Outbox Generic event, time, currency, value, internal idempotency key Schema validation
Queue Same minimum payload and retry metadata Queue role and region
External upload Only approved generic conversion fields Counsel and tenant approval

Compare the delivery boundary with AWS Lambda runtime controls and the generic offline conversion payload. For broader advertising policy review, use Google Ads health conversion policy.

Request, data, key, and identity path

Make the outbox write part of the same trusted decision as the source update. Resolve tenant membership server-side, verify that the source event is eligible, create an internal idempotency key, and commit the source state plus outbox intent. Do not let a browser enqueue an external conversion or select a destination.

The outbound schema should be deliberately boring: a generic conversion name such as appointment_completed, an approved event time, currency, and value. The exact fields and retention need tenant-specific legal approval. Do not add a person’s name, email address, phone number, a hashed contact identifier, service or treatment name, or free-text description. Do not assume hashing makes a prohibited identifier safe.

Use separate identities for source writes, queue writes, queue reads, validation, and external upload. The upload identity should not be able to read the source database. The validation worker should be able to reject fields and mark a review state without having permission to send. A human approval path should be auditable and expire when its scope changes.

source outcome
  -> tenant approval check
  -> source update + outbox row
  -> SQS message with generic payload
  -> idempotent worker
  -> approval and policy gate
  -> external upload only when enabled

Keep the internal and external identifiers distinct. An idempotency key prevents duplicate workers from uploading the same approved event. It does not prove that the event is permitted to leave the platform. Store delivery result, attempt count, timestamp, and reason code without copying the original booking record.

Queue, audit, backup, and failure handling

Reliability requires retries that never turn into uncontrolled disclosure. Use visibility timeout, bounded retries, a dead-letter queue, and an operator review state. A transient network failure should retry the same minimum payload. A schema or approval failure should stop and quarantine the event, not retry indefinitely.

Deduplication needs a clear contract. The source transaction creates one internal event key. The worker records an attempt and the external response. A retry after an unknown response must check the provider’s supported idempotency or reconciliation behavior before sending again. Do not solve duplicate risk by adding more patient or booking identifiers to the payload.

Audit the gate. Record tenant, generic event type, decision, approval version, worker identity, attempt, result, and time. Keep patient names, email addresses, phones, hashed identifiers, service details, and clinical content out of logs and dead letters. Review queue access, admin access, export, backup, and restore separately.

Test the failure matrix with synthetic data: source transaction rolls back, queue write fails, worker times out, external response is unknown, approval is revoked, schema changes, and dead-letter replay occurs. The expected outcome is either safe retry, controlled quarantine, or no delivery. Every path should identify an owner.

Cost and proof gate

Price the queue and the control surface separately. AWS SQS pricing is one input. Add worker runtime, logging, storage, encryption keys, dead-letter retention, network transfer, external API quota, review time, and incident handling. Label all numbers as estimates with region, volume, retention, and retrieval date.

Do not optimize for the lowest upload count by broadening the event. The correct question is whether the approved generic conversion supports the tenant’s measurement objective without prohibited data. If not, leave the external gate disabled. A queue that holds approved internal outcomes remains useful for reconciliation even when outbound delivery is off.

  • Commit source outcome and outbox intent together.
  • Validate a generic payload before queueing and again before upload.
  • Use tenant approval state as a fail-closed gate.
  • Separate retry, dead-letter, review, and upload identities.
  • Never add prohibited identifiers to improve matching.

Outbound conversion proof

Prove the gate with delivery disabled first.

  1. Create a synthetic approved outcome and verify one outbox entry.
  2. Replay the message and confirm one internal event key.
  3. Remove tenant approval and confirm no external request occurs.
  4. Add a prohibited field in a test fixture and confirm schema rejection.
  5. Force timeout and unknown response, then inspect retry and dead-letter behavior.
  6. Re-enable delivery only after counsel and tenant approval are recorded.
  7. Review the provider response, audit evidence, and deletion or retention path.

The implementation should make the external gate visible in configuration and logs without exposing secrets. Do not describe a successful test upload as legal approval. The final record should name the approved fields, tenant, date, owner, and conditions under which the gate must close again.

Keep an approval record beside the event schema. It should identify tenant, approved conversion name, fields, purpose, retention, destination, legal reviewer, customer approver, date, and expiry or review trigger. If a tenant changes its policy, stop the upload gate and quarantine pending events until the new decision is recorded. Do not replay an old approval against a changed payload.

Use separate internal and external queues when their retention or access differs. The internal queue can support reconciliation while delivery remains disabled. The external worker should read only events that pass the current gate. A dead-letter queue should preserve reason code and retry metadata, not a full booking record. Review queue readers and administrators separately from source-data readers.

Test the source transaction and outbox together. Force a source rollback, queue failure, worker crash, unknown external response, duplicate message, approval revocation, schema rejection, and dead-letter replay. For each case, record whether the result is retry, quarantine, review, or no delivery. The important proof is not that one upload succeeds; it is that an unapproved upload cannot happen.

Keep the Google Ads path intentionally narrow. The generic event can use an approved conversion name, event time, currency, and conversion value. Do not add patient name, email, phone, hashed identifier, service name, treatment detail, or clinical text for matching. A platform API field being available does not make its use appropriate. Counsel and each tenant must approve the exact payload, and the gate must default off.

Price SQS requests, worker runtime, log ingestion, dead-letter retention, keys, network transfer, external API quota, and human review. A low queue price does not offset a broad disclosure. Recheck Google Ads policy and API documentation before enabling a tenant. See one primary conversion source for a related deduplication boundary.

Frequently asked questions

What should an approved generic payload contain?

Use only fields explicitly approved for the tenant and use case. A conservative example is generic conversion name, event time, currency, and value. Do not include patient name, email, phone, hashed identifier, service or treatment detail, or clinical text.

Does SQS make an upload safe?

No. SQS provides queue behavior and pricing. The application still controls data minimization, identity, approval, retries, dead letters, audit, and whether an external upload happens.

What happens when approval is revoked?

Stop external delivery, retain only the minimum internal record required by policy, quarantine pending messages, and review whether already delivered events require action. The customer and counsel should define the revocation procedure.

Can hashing make a contact identifier acceptable?

Do not assume that. The stated gate here prohibits patient name, email, phone, and hashed identifiers. Use a generic conversion payload and obtain tenant-specific legal approval for any alternative.

References

Related articles