Skip to main content

AsyncAPI Webhook Contract

QuickstartAPI ReferenceAuth GuideWebhooksFHIR & HL7SAML / SCIM SSOOpenAPI & SwaggerAPI VersioningAsyncAPI ContractSDK PackagingEvent SchemasRecipesTroubleshooting

AsyncAPI Webhook Contract

Last updated: 2026-02-18

Bounded Health now publishes a machine-readable AsyncAPI contract for outbound webhook events.

1. Contract endpoint

  • GET /api/asyncapi
  • Format: AsyncAPI 2.6.0 JSON

2. Covered event channels

Channels are emitted as webhooks/{eventName} and include:

  • webhooks/test.ping
  • webhooks/tapering.proposed
  • webhooks/tapering.approved
  • webhooks/tapering.declined
  • webhooks/simulation.completed
  • webhooks/cohort.uploaded
  • webhooks/authorization.reviewed
  • webhooks/export.ready
  • webhooks/invoice.paid

3. Payload/headers

Each message declares:

  • HMAC signature header: x-webhook-signature
  • Delivery metadata headers: x-webhook-id, x-webhook-event, x-webhook-version, x-webhook-timestamp
  • Payload envelope fields: id, event, timestamp, apiVersion, employerId, data

4. Verification workflow

  1. Pull latest AsyncAPI contract from /api/asyncapi
  2. Generate or validate webhook consumers with AsyncAPI tooling
  3. Validate HMAC signatures before processing payloads (validateInboundWebhook in SDK)
  4. Enforce idempotency using x-webhook-id (checkAndStoreWebhookIdempotency in SDK)

4.1 SDK helper implementation

Webhook consumer helpers are shipped in:

  • sdks/typescript/src/webhooks.ts
  • sdks/typescript/src/webhooks.test.ts

Capabilities:

  • Signature verification (x-webhook-signature)
  • Header/payload consistency validation (x-webhook-id, x-webhook-event, x-webhook-version, x-webhook-timestamp)
  • Non-retryable schema errors for missing required fields
  • Idempotency tracking by webhook id

5. Snapshot export

Use:

bash
npm run contracts:export

This writes a versioned snapshot to:

  • docs/integration-opportunities/contracts/asyncapi.webhooks.v1.json