docs(run-payerbox): document AidboxTopicDestination event notifications

[not-in-stock]

What

Adds an operator how-to for outbound event notifications — Payerbox's topic-based subscription mechanism — which was previously undocumented.

New page: Run Payerbox → Maintain → Event Notifications (docs/run-payerbox/maintain/event-notifications.md).

Contents

• How it works: AidboxSubscriptionTopic (trigger) + AidboxTopicDestination (sink), async delivery via the engine.
• At-least-once vs best-effort delivery.
• Destination kind table — webhook-at-least-once, aws-sns-*, and the Payerbox custom-aws-sns-* kinds (with reference enrichment).
• Step-by-step configuration: allow-destinations profile whitelist → subscription topic → destination (SNS / webhook tabs, full parameter tables) → verify.
• Deploy-time provisioning via init-bundle and the ordering rules.
• Immutability: destinations are delete-and-re-create only; re-creation re-registers with the delivery engine.
• Gotchas (idempotency, re-fire, stale config) and current limitations.

Examples are grounded in the actual SNS module and seed configuration, not paraphrased.

Wiring

• Listed in SUMMARY.md under Maintain.
• Linked from the Maintain index (maintain/README.md).

Checks

bun lint (docs-tools) — 13 checks passed; no warnings on the new page. Remaining repo warnings are pre-existing and unrelated.

Resolves HealthSamurai/smartbox#497

[not-in-stock]

/qa

[qa-assist-bot]

QA Report — PR #17: document AidboxTopicDestination event notifications

Repo: HealthSamurai/payerbox-docs
PR: #17 — docs(run-payerbox): document AidboxTopicDestination event notifications
Resolves: HealthSamurai/smartbox#497
Date: 2026-06-23

Summary

PR #17 adds a new operator how-to page Event Notifications (docs/run-payerbox/maintain/event-notifications.md) documenting Payerbox's topic-based subscription mechanism for pushing FHIR resource events to AWS SNS or HTTP webhooks.

Changes

File	Change
SUMMARY.md	Added Event Notifications entry under Maintain
docs/run-payerbox/maintain/README.md	Added row linking to the new page with a short description
docs/run-payerbox/maintain/event-notifications.md	New — 241 lines covering architecture, destination kinds, step-by-step configuration (whitelist → topic → destination → verify), deploy-time provisioning, immutability gotchas, and current limitations

Content covered

• How it works: AidboxSubscriptionTopic (trigger) + AidboxTopicDestination (sink), async delivery.
• At-least-once vs best-effort delivery guarantees.
• Destination kind table — 5 kinds including Payerbox-specific custom-aws-sns-* with reference enrichment.
• Step-by-step configuration with tabbed examples (AWS SNS / HTTP webhook), full parameter tables.
• Deploy-time provisioning via init-bundle with ordering rules.
• Immutability semantics (delete-and-re-create only) and re-registration behavior.
• Gotchas (idempotency, re-fire loops, stale config) and current limitations.

Documentation analysis

Structure & wiring

• SUMMARY.md: Entry is correctly placed under Maintain, between Observability and Upgrade. Indentation level is correct (4 spaces, child of Maintain).
• Maintain index (maintain/README.md): New row added to the table with a clear one-line description.
• Heading hierarchy: H1 → H2 → H3 — no skipped levels. Lint confirms heading-order passes.

Cross-references

The new page links to three existing pages via GitBook content-ref widgets:

• observability.md — exists, valid relative path.
• ../architecture.md — exists, valid relative path.
• ../../prior-auth/pas.md — exists, valid relative path.

It also has an inline link to [Architecture](../architecture.md) in the opening paragraph. All links resolve — lint's broken-links check passes with 0 issues.

Content quality

Aspect	Assessment
Accuracy	JSON examples use correct Aidbox resource types (AidboxSubscriptionTopic, AidboxTopicDestination), valid meta.profile URLs, and realistic parameter structures. The PAS ClaimResponse example is domain-appropriate.
Completeness	All 5 destination kinds are documented. Both SNS and webhook transports have full parameter tables. The custom Payerbox extension (custom-aws-sns-*) is clearly distinguished from the vanilla Aidbox kinds.
Actionability	Step-by-step stepper widget with numbered phases. Each step has a code example and explanation. Prerequisites section is present.
Warnings / hints	Appropriate {% hint %} blocks for: IAM role preference over long-lived keys, immutability warning, queue observation caveat.
Diagram	Mermaid flow diagram clearly shows the write → topic → destination → external system pipeline.
Edge cases	Covers FIFO topics (messageGroupId), endpoint override for local testing, reference enrichment toggle, re-registration after restart.
Frontmatter	Present with a meaningful description suitable for SEO / GitBook metadata.

Lint results

bun run lint:json on the PR branch:

• 0 errors across all 16 checks
• 4 pre-existing warnings (absolute-links, title-mismatch, orphan-pages, dead-end-pages) — none on the new page
• The new page introduces no new warnings

Test environment

This is a documentation-only repository (GitBook). No running application or Docker environment is needed. Testing focuses on structural integrity, link resolution, lint compliance, and content quality review.

Test cases

Lint & structure

ID	Status	Description	Expected	Result
TC-01	PASS	docs-lint reports 0 errors on the PR branch	totalErrors: 0	totalErrors: 0, totalWarnings: 4 (all pre-existing)
TC-02	PASS	New page is listed in SUMMARY.md under Maintain	Entry present	* [Event Notifications](run-payerbox/maintain/event-notifications.md) between Observability and Upgrade
TC-03	PASS	New page is linked from Maintain index README.md	Link present	Row added with description "Push FHIR events to AWS SNS or webhooks via topic-based subscriptions"
TC-04	PASS	No broken internal links on the new page	0 broken-links issues	broken-links check: 0 issues across 59 files
TC-05	PASS	No summary-sync issues	0 summary-sync issues	summary-sync check: 0 issues

Cross-references

ID	Status	Description	Expected	Result
TC-06	PASS	Cross-ref to architecture.md resolves	File exists	docs/run-payerbox/architecture.md exists on PR branch
TC-07	PASS	Cross-ref to observability.md resolves	File exists	docs/run-payerbox/maintain/observability.md exists on PR branch
TC-08	PASS	Cross-ref to prior-auth/pas.md resolves	File exists	docs/prior-auth/pas.md exists on PR branch

Content quality

ID	Status	Description	Expected	Result
TC-09	PASS	Page has frontmatter with description	description: in YAML frontmatter	Present: "Push FHIR resource events from Payerbox to AWS SNS or HTTP webhooks…"
TC-10	PASS	Page has correct H1 heading	# Event Notifications	Matches SUMMARY.md title — no title-mismatch warning
TC-11	PASS	All 5 destination kinds documented in table	All kinds listed	webhook-at-least-once, aws-sns-at-least-once, aws-sns-best-effort, custom-aws-sns-at-least-once, custom-aws-sns-best-effort — all present with profiles
TC-12	PASS	Configuration includes SNS and webhook tabs	Both tabs present	{% tab title="AWS SNS" %} and {% tab title="HTTP webhook" %} with full JSON examples
TC-13	PASS	Page includes Mermaid architecture diagram	Diagram present	Flow: FHIR write → AidboxSubscriptionTopic → AidboxTopicDestination → External system

Conclusion

Result: PASS (13/13)

PR #17 adds a well-structured, comprehensive documentation page for Payerbox Event Notifications. All checks pass:

• Lint: Zero errors introduced; zero new warnings.
• Wiring: Correctly linked in SUMMARY.md and Maintain index.
• Cross-references: All internal links resolve.
• Content: Thorough coverage of all destination kinds, step-by-step configuration with both SNS and webhook examples, deploy-time provisioning, gotchas, and limitations. Code examples are realistic and well-annotated.

No issues found. The PR is ready for merge.

---

cc @Aitem @not-in-stock