Webhooks overview

Webhooks are how QairoPay tells your code that state has changed. Polling is supported but discouraged for anything time-sensitive: pass installations, card authorizations, settlement completions, and KYC outcomes all reach you fastest through webhooks.

Envelope

Every event has the same shape:

{
  "id": "evt_01HZX...",
  "type": "pass.installed",
  "created": "2026-05-19T10:14:22.184Z",
  "tenant_id": "tnt_01HZX...",
  "live_mode": false,
  "api_version": "2026-05-19",
  "data": {
    "pass": { "id": "pass_01HZX...", "...": "..." }
  },
  "previous_attributes": null
}

id — unique event id. Idempotent processing key.
type — dotted-namespace event type. Always present, always strings.
tenant_id — which tenant this event belongs to. Critical for multi-tenant integrations.
live_mode — false for sandbox events, true for live.
api_version — the version of the schema inside data. Pin to a version in the dashboard.
data — the resource snapshot at the time of the event. Always contains the full resource.
previous_attributes — for *.updated events, the fields that changed and their old values.

The same event id can be retried; treat receipt as at-least-once delivery and process idempotently (use id as your dedup key).

Registering an endpoint

In the dashboard, Developers → Webhooks → New endpoint. You provide:

A URL (HTTPS only; http:// is rejected even for localhost).
A set of event types to subscribe to (default: all in the selected products).
An optional description.

QairoPay generates a signing secret on creation. Copy it once and store it in your secret manager — you’ll use it to verify signatures (see Signing).

You can also create endpoints via the API:

await qp.webhooks.endpoints.create({
  url: "https://api.acme.example/qairopay/webhooks",
  enabled_events: ["pass.*", "card.transaction.authorized"],
  description: "Production primary endpoint",
});

How many endpoints

Most customers run two endpoints in production:

Primary — your main integration handler.
Backup / observability — a separate service that just logs events for replay and forensics.

Spreading delivery across two endpoints protects against your primary handler having a bad deploy and missing events. The backup endpoint can be a tiny S3-writer if that’s all you need.

In sandbox, also use the dashboard inspector as a third endpoint while you develop — events show up in the dashboard UI immediately and you can replay them on demand.

Event types you should care about

Domain	Most important events
Pass	`pass.created`, `pass.installed`, `pass.updated`, `pass.scanned`, `pass.revoked`
Card	`card.created`, `card.activated`, `card.transaction.authorized`, `card.transaction.captured`, `dispute.updated`
Settlement	`settlement.completed`, `settlement.failed`, `payout.completed`
Compliance	`cardholder.kyc.completed`, `cardholder.sanctions.alert`
Program	`program.activated`, `program.suspended`

The full catalog is at Webhooks → Events.

What’s next

Signing and verification — verify every payload before you trust it.
Retries and delivery — what we do when your endpoint is unreachable, and how to scale.
Event catalog — the full list with payload schemas.