Skip to main content

Webhooks

Some events across ARC and ePrescription happen asynchronously:

  • A sponsor evaluates an authorization request offline and issues (or rejects) the authorization minutes or hours later.
  • A pharmacy completes a dispensation that your system originated.
  • An electronic prescription is issued and the patient email is delivered.

For all of these, Osigu doesn't ask you to poll. It calls you — an HTTPS POST from Osigu's webhook dispatcher to an endpoint your team owns. Payloads are JSON, and every request carries an X-Osigu-Signature header that lets you verify it came from us.

For the full event catalogue and payload shapes, see Webhook events.

When to reach for webhooks vs polling​

SituationWebhookPoll
Sponsor evaluates asynchronously (returns PENDING_SPONSOR)✅❌
Pharmacy dispensations that you don't initiate but affect your authorizations✅❌
You want a stale-eventually view of dispensation status✅ or poll✅
One-off manual reconciliation❌✅

The delivery contract​

  • Method: HTTPS POST (Osigu will not follow redirects).
  • Content-Type: application/json.
  • Body: a signed envelope containing event_id, event_type, created_at, data, and version metadata.
  • Signature: X-Osigu-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>.
  • Retries: Osigu retries on any 5xx or timeout for 72 hours with exponential backoff. 2xx = delivered.
  • Timeout: 10 seconds. Return a response quickly; do the heavy work off the request thread.

Signature verification​

Compute HMAC-SHA256 over <timestamp>.<raw_request_body> using the shared secret Osigu gave you at onboarding, and compare against the v1= value in the signature header. Reject the request if:

  1. The signature doesn't match, or
  2. The t= timestamp is more than 5 minutes off from now (replay protection).

Full end-to-end example in Implement a webhook receiver.

Idempotency​

The same event can be delivered more than once. This happens when your endpoint returns 2xx but the response takes too long to reach us. Every event carries an event_id. Persist processed event_ids and short-circuit on duplicates — either idempotency by primary key (preferred) or a small dedupe cache with TTL.

Event categories​

Events belong to one of four families, each with its own set of types:

  • authorization.* — created, rejected, voided, updated.
  • dispensing.* — started, completed, cancelled.
  • prescription.* — issued, email_delivered, email_failed.
  • settlement.* — dispatched, paid, rejected (Dominican Republic flow only).

Full catalogue: Webhook events reference.