Webhooks v2 — Overview

What changed in v2

Webhooks v2 introduces two independent improvements:

Existing webhooks default to v1. Newly created webhooks default to v2.

Payload versioning

Every v2 payload carries a fixed api_version field:

{
  "event_type": "order_created",
  "event_id": "event::abc123",
  "api_version": "2026-08-09",
  "timestamp": "2026-05-30T14:00:00.000Z",
  "affiliate_id": "aff::xyz",
  "order_id": "order::abc"
}

The api_version value for most v2 envelopes is 2026-08-09. It identifies the payload schema and will be bumped if a breaking change is ever made. Journey-native events are the exception and use "2026-08-06" (see Versioning guarantees).

⚠️

timestamp is the delivery-attempt time, not the event's creation time — it is regenerated on every retry. Don't use it to order or dedupe events; use event_id for dedup and reconcile state per entity for ordering (see Delivery & Retries).

PHI sanitization — per-category allowlists

PHI is removed from v2 payloads at dispatch time. Each event category has an explicit allowlist governing which eventData fields pass through; any field not on the list is stripped before delivery. patient_id does not appear on any category's allowlist below — but every v2 payload, regardless of category, also carries four patient-identity fields (patient_id, patient_external_id, patient_marketing_consent, is_returning_patient) added by a separate, always-on enrichment step that isn't governed by the category allowlist at all.

There is no SUBSCRIPTION or CHANNEL category — subscription fields (subscription_id, subscription_status) are exposed under COMMERCE and ORDER/JOURNEY instead.

Beyond the allowlist, a separate blocklist strips known-PHI keys (email, phone, firstName/lastName, dateOfBirth, address/city/state/zip, medications, allergies, diagnosis, clinicalNotes, credentials/tokens, and others) as defense in depth if they ever appear on an allowlisted path.

Field coverage on v2 payloads

The allowlist above only keeps an eventData field if its name matches an allowlist entry (directly, or via a small alias table). Events introduced alongside the v2 payload system (Journey, Commerce/subscription, Payment events) use field names that match their category's allowlist, so their v2 payloads carry full detail. Patient events (patient_enrolled) carry full detail too, but for a different reason — their entire meaningful payload is the universal patient-identity fields described above, not anything from the (empty) PATIENT category allowlist.

Most events now include their event-specific fields directly in v2 payloads. Where detail is not included in the payload itself, it is retrievable through the authenticated API using the entity IDs the payload delivers — v2 payloads are designed as notifications, not data transfers. Status reasons and order-history details are retrievable through dedicated endpoints without requiring v1 payloads.

Migration path

1. Create a new webhook or use the upgrade endpoint to switch an existing webhook to v2 payload delivery.
2. Update your consumer to verify the new signature format (see Signature Verification).
3. Remove any code that expects PHI fields — they will not appear in v2 payloads.
4. If you need to roll back from v2 to v1, use the rollback endpoint (requires master token).

Event dictionary

The webhook dictionary defines 59 event types, of which 56 are publicly subscribable by affiliates. Two are internal-only (never delivered to affiliate webhooks), and one additional public event (pharmacy_rejected_prescription) is defined but not yet implemented — it is excluded from subscription (56 + 2 + 1 = 59). All 56 subscribable events are emitted by live code paths. To retrieve the full list programmatically:

GET /webhooks/actions/getDictionary

Note this endpoint lives on the legacy v1 webhook management API (/webhooks/...), not the /v2/webhooks/... module — it predates payload versioning and works the same regardless of which payload version your webhook is configured for. See the getDictionary endpoint for the response shape.

For a complete per-event breakdown of which fields are guaranteed, conditional, or not delivered, see Field Guarantees.

For narrative documentation of individual events (purpose, example payload), see the event pages under each category: Order, Prescription, Pharmacy, Lab, Payment, Journey, Commerce, Patient, and Support Events.

Versioning guarantees

• Most v2 envelopes use api_version: "2026-08-09". This replaced "2026-05-24" when marketing attribution was extended beyond journey events — see Attribution Passthrough. The change is additive: consumers that ignore unknown fields need no action.
• Exception — Journey-native events (journey_checkout_started, journey_completed, journey_abandoned) always use api_version: "2026-08-06", including when the optional attribution key is omitted. See Attribution Passthrough.
• Within a given api_version, fields are additive (never removed or renamed). Adding a significant new block such as attribution may still bump api_version so documentation and consumers can target the schema explicitly — as with the Journey bump to "2026-08-06".
• Breaking changes (field removal, rename, type change) always bump api_version and are announced in advance.