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-17",
  "timestamp": "2026-05-30T14:00:00.000Z",
  "timestamp_epoch": 1780149600,
  "affiliate_id": "aff::xyz",
  "order_id": "order::abc"
}

The api_version value is 2026-08-17. It identifies the payload schema and will be bumped if a breaking change is ever made.

⚠️

timestamp is the delivery-attempt time, not the event's creation time — it is regenerated on every retry. timestamp_epoch is the same instant as integer Unix seconds. Don't use either 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 also carries a patient-identity block added by a separate enrichment step that isn't governed by the category allowlist. patient_marketing_consent and is_returning_patient are always present (default false). patient_id and patient_external_id are omitted when unavailable — never sent as null. patient_id is present when the event has a linked patient; patient_external_id is present only when that patient also has an external identifier.

is_returning_patient is per-patient, not per-order: true when the patient already has another ecommerce order in paid, processing, or completed.

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

product_display_names and products[].display_name are not delivered. Product line items are { product_variation_id, quantity, unit_price_cents, is_addon }. Money is integer cents (84900 = $849.00).

first_purchase is true only when the order is not a renewal. subscription_renewed always sends first_purchase: false. journey_contact_captured never includes it (no order yet). journey_abandoned includes it only when had_cart is true. See Subscription Renewed.

attribution (including optional landing_url / referrer_url on first/last touch) is documented in Attribution Passthrough. SUPPORT, PATIENT, and INTERNAL do not receive it.

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 60 event types. 58 are public (returned by getDictionary). Two are internal-only (never delivered to affiliate webhooks). One public event (pharmacy_rejected_prescription) is defined but not yet implemented and is excluded from Affiliate Admin subscription — 57 events are command-subscribable, including journey_contact_captured and custom_intake_form_completed. All 57 command-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

• api_version: "2026-08-17" is the current v2 schema version (journey and generic envelopes share this value).
• Within 2026-08-17, fields are additive except the documented removal of products[].display_name / product_display_names.
• Breaking changes (field removal, rename, type change) will bump api_version and be announced in advance.

Changelog vs 2026-08-09

Additive:

• first_purchase, plan_type, cycle_number
• timestamp_epoch; journey event_id is derived from the Event _id and remains stable across every delivery attempt
• had_cart; recovery_status / recovery_missing_details no longer stripped
• journey_contact_captured
• attribution.first|last.landing_url / referrer_url when captured (omit when absent)

Removed:

• products[].display_name and unused product_display_names