Part 4 · 2 chapters · ~12 min

Events and AsyncAPI

Events as public contracts, AsyncAPI specifications, CloudEvents envelopes, schema registries and compatibility modes, thin versus fat events, ordering and keys, webhooks for partners with signing, retries, delivery logs and replay.

9

Designing event contracts

code
# AsyncAPI (excerpt)
asyncapi: 3.0.0
info: { title: Transfers events, version: 1.4.0 }
channels:
  transferCompleted:
    address: bank.transfers.completed.v1
    messages: { TransferCompleted: { payload: { $ref: '#/components/schemas/TransferCompleted' } } }
components:
  schemas:
    TransferCompleted:
      type: object
      required: [transfer_id, account_id, amount, completed_at]
      properties: { transfer_id: { type: string }, account_id: { type: string },
                    amount: { $ref: '#/components/schemas/Money' }, completed_at: { type: string, format: date-time } }
EVENTS AS AN API
webhooks and published events are contracts too
transfers serviceemits eventsschema registryAvro / JSON Schema / ProtobufKafka / SNSinternal consumerswebhook dispatcherpartners, signed
swipe the figure sideways, or tap expand for full screen
1/5
events are contracts
An event (TransferCompleted) published for others to consume is an API with the same compatibility obligations as an endpoint. Describe it with AsyncAPI or registered schemas.
events need specs and compatibility rulesAsyncAPI, schema registries
10

Webhooks for partners

a webhook contract partners will trust
  1. Signed with a per-partner secret (HMAC over timestamp + body) and a documented verification recipe.
  2. At least once, with an event id for deduplication, and no ordering promise unless stated.
  3. Retries with exponential backoff for 24-72 hours, then marked failed.
  4. A delivery log and replay in the partner dashboard.
  5. Thin events plus a fetch endpoint for sensitive data, so payloads leak less.