Skip to main content

Webhook events

This section catalogues every event Osigu emits to your webhook receiver — the event types, the payload shape, the delivery semantics.

If you haven't built a receiver yet, start with the Webhooks concept and the Implement a webhook receiver guide. Come back here when you need to know exactly what to expect for a given event_type.

Event envelope​

Every event Osigu POSTs has this shape:

{
  "event_id": "evt_01HXY2Z4A5B6C7D8E9F0G1H2J3",
  "event_type": "authorization.created",
  "created_at": "2026-06-25T14:22:11.789Z",
  "api_version": "2026-01-01",
  "environment": "sandbox",
  "data": {
    // event-specific — see per-family pages
  },
  "provider": {
    "provider_id": "prv_...",
    "provider_slug": "clinic-example"
  }
}

Common fields:

FieldTypePurpose
event_idstringStable, unique per event. Use it for deduplication.
event_typestringDot-namespaced type. Match on the prefix (e.g. authorization.*).
created_atISO 8601When Osigu emitted the event.
api_versiondateVersion of the envelope schema. See Versioning below.
environmentsandbox | productionWhich environment produced the event. Prevents sandbox events from being mis-processed in production and vice versa.
dataobjectEvent-specific payload.
providerobjectThe provider the event scopes to.

Event families​

authorization.*

Emitted whenever a pre-authorization changes state — sponsor decisions, voids, modifications.

dispensing.*

Emitted whenever a dispensation starts, completes, or is cancelled at the pharmacy.

prescription.*

Emitted whenever an electronic prescription is issued, delivered, or fails delivery.

settlement.*

Dominican Republic radicación flow. settlement.paid, settlement.rejected, settlement.partially_accepted.

Delivery guarantees​

  • At-least-once. The same event_id may be delivered multiple times. Dedupe on your side.
  • Roughly ordered per resource. Events for the same authorization_id are usually delivered in the order they occurred, but this is best-effort — do not depend on strict ordering. Use created_at if you need a total order.
  • Retries for 72h. Non-2xx responses trigger exponential backoff for up to 72h, then abandonment.
  • Timeout 10s. Return 2xx quickly; do the heavy work off-thread.

Event versioning​

The envelope is versioned by api_version (a stable date string). When Osigu changes the envelope shape breakingly, we bump this value and give a 6-month migration window.

Individual data payloads evolve additively — new fields may appear at any time. Your parser should ignore unknown fields.

Sample dispatch​

Here's a dispensing.completed example your receiver would see:

{
  "event_id": "evt_01HXY2Z4A5B6C7D8E9F0G1H2J3",
  "event_type": "dispensing.completed",
  "created_at": "2026-06-25T14:22:11.789Z",
  "api_version": "2026-01-01",
  "environment": "sandbox",
  "data": {
    "dispensation_id": "dsp_01HXDN...",
    "authorization_code": "AUTH-2026-001234",
    "beneficiary_id": "bnf_01HW8GQ...",
    "sponsor_slug": "sponsor-sandbox",
    "products": [
      { "product_code": "MED-042", "quantity": 30, "unit_price": 12.50 }
    ],
    "dispensed_at": "2026-06-25T14:22:00.123Z"
  },
  "provider": { "provider_id": "prv_...", "provider_slug": "clinic-example" }
}

Verify the signature, dedupe on event_id, and route on event_type. See signature verification for the HMAC details and payload reference for a compact table of every event_type.