Webhooks

We offer Webhooks to alert partners of relevant events in the Yuzu portal and have developed a self-serve process to integrate.

Create a webhook

Left sidebar
Current Organization
‘Settings’

‘Developer’

Event Configurations ‘+ Create’

Event types

We currently support a variety of events across the app, this list is updated regularly so check the drop-down for the latest.

Webhook event catalogue

The webhook body carries only the object ID in payload.id; use the GET route to fetch the object.

Member

Event	When it is sent	`payload.id` is	Fetch with
`member_new`	Not currently sent by the enrollment process; new members receive `member_update`.	Member ID	`GET /v1/members/{id}`
`member_update`	A member is enrolled, or member, coverage, fee, other insurance, or account details change.	Member ID	`GET /v1/members/{id}`
`member_termedCobraEligible`	A member reaches the COBRA election-notice step after coverage loss, including members without email.	Member ID	`GET /v1/members/{id}`
`member_cobraElected`	A member elects COBRA through the member form and awaits payment.	Member ID	`GET /v1/members/{id}`
`member_ageoutWarning`	A child approaches age 26 under the plan's end-of-month age-out rule.	Member ID	`GET /v1/members/{id}`
`member_undeliverableWarning`	An address changes to undeliverable through a member edit or returned-mail action.	Member ID	`GET /v1/members/{id}`

What counts as a member update

Enrollment changes

A subscriber or dependent is added.
Initial enrollment is filed by form or API.
An HRIS or 834 enrollment file is applied.
A qualifying life event enrollment is applied.
An invited subscriber completes enrollment.
Employment or coverage ends, including life-event terminations and correction of mistaken enrollment.
An enrollment is annulled or voided.
Coverage dates or policy dates change.
A primary care provider changes.
COBRA coverage is changed or cancelled.
Coverage is renewed.
A member changes plans, individually or in a bulk change.
A dependent becomes a subscriber.

Member detail edits

Personal details or an address are edited through the API or portal.
Portal contact details or communication preferences change.
An age-out exception changes.
Claim staging settings or the list of members excluded from matching changes.

Coverage detail edits

An alternate member ID changes.
A hire or retirement date changes.
Location, department, or employee class changes.
Cash-card eligibility changes.

Fees

A fee assignment is added.
A fee assignment or its dates change.
A fee assignment is removed.

Coordination of benefits

An other-insurance record is added or edited in the portal.
An other-insurance review is marked complete or reset.
A Medicare or commercial insurance form records other coverage.
An incoming claim identifies new other-insurance information.

Account

An account settings change updates the member's email or phone number.

A communication-preference change alone in account settings does not send this event.

Medical claim

Event	When it is sent	`payload.id` is	Fetch with
`medicalClaim_new`	A medical claim is created or received, or a failed deletion leaves the claim in place.	Claim ID	`GET /v1/claims/medical/{id}`
`medicalClaim_update`	Claim details, amounts, coverage, or the claim decision change.	Claim ID	`GET /v1/claims/medical/{id}`
`medicalClaim_delete`	A medical claim is about to be deleted.	Claim ID	`GET /v1/claims/medical/{id}`

What counts as a medical claim update

A manually entered claim is edited, including its billed amount.
A manually entered claim is voided.
A cash-card swipe void or refund voids the linked claim or reduces its billed amount.
An incoming claim adjusts, reverses, voids, or reprices an existing claim.
A claim moves to another coverage, individually or in bulk, including moves from annulled coverage.
A claim decision is submitted or resubmitted, automatically or manually, including cash-card decisions and a return to Processing.
The current claim decision version is deleted.
The claim decision is reset.

After a successful deletion, the GET route cannot return the claim.

Pharmacy claim

Event	When it is sent	`payload.id` is	Fetch with
`pharmacyClaim_new`	A pharmacy claim is created or received, or a failed deletion leaves the claim in place.	Claim ID	`GET /v1/claims/pharmacy/{id}`
`pharmacyClaim_update`	Claim details, amounts, coverage, or the claim decision change, or source data is reprocessed.	Claim ID	`GET /v1/claims/pharmacy/{id}`
`pharmacyClaim_delete`	A pharmacy claim is about to be deleted.	Claim ID	`GET /v1/claims/pharmacy/{id}`

What counts as a pharmacy claim update

A manually entered claim is edited, including its billed amount.
A manually entered claim is voided.
An incoming claim adjusts, reverses, voids, or reprices an existing claim.
A claim moves to another coverage, individually or in bulk, including moves from annulled coverage.
A claim decision is submitted or resubmitted.
The current claim decision version is deleted.
The claim decision is reset.
A pharmacy claim is reprocessed from its stored source data.

After a successful deletion, the GET route cannot return the claim.

Precert

Event	When it is sent	`payload.id` is	Fetch with
`preCert_new`	A precertification is created by manual upload or an incoming partner file.	Precertification ID	`GET /v1/preCerts/{id}`
`preCert_update`	A manually uploaded precertification is edited, or a precertification moves to another coverage.	Precertification ID	`GET /v1/preCerts/{id}`

What counts as a precert update

A manual edit replaces details, status, diagnosis codes, procedure codes, service lines, or providers.
A precertification moves to another coverage, including an approved move to another member.

Changes to existing precertifications from partner files do not send preCert_update.

Cash card

Event	When it is sent	`payload.id` is	Fetch with
`cashCard_requested`	A new request needs review, or an existing request is resubmitted.	Cash-card ID	`GET /v1/cashCards/{id}`
`cashCard_approved`	An approval action completes card creation.	Cash-card ID	`GET /v1/cashCards/{id}`
`cashCard_paused`	A user pauses a card, or a swipe limit or visit limit pauses it.	Cash-card ID	`GET /v1/cashCards/{id}`
`cashCard_cancelled`	A user cancels a card, or coverage, inactivity, settlement, spending, expiry, or visit-limit rules cancel it.	Cash-card ID	`GET /v1/cashCards/{id}`
`cashCard_swiped`	A card swipe is processed.	Cash-card ID	`GET /v1/cashCards/{id}`
`cashCard_swipeVoided`	A voided card swipe is processed.	Cash-card ID	`GET /v1/cashCards/{id}`
`cashCard_refunded`	A refund is booked, including refunds that need review or cannot be matched to one claim.	Cash-card ID	`GET /v1/cashCards/{id}`

A refund event does not confirm that the claim decision was updated. Unpausing a card does not send an event.

Enrollment request

Event	When it is sent	`payload.id` is	Fetch with
`enrollmentRequest_submitted`	An enrollment request completes preparation and reaches processing; enrollment is not yet confirmed.	Enrollment request ID	`GET /v1/enrollmentRequests/{id}`
`enrollmentRequest_assigned`	An enrollment request is assigned to an employee.	Enrollment request ID	`GET /v1/enrollmentRequests/{id}`
`enrollmentRequest_hrisFailure`	An HRIS enrollment application fails, including recorded 834 validation failures or enrollment-rule refusals.	Enrollment request ID	`GET /v1/enrollmentRequests/{id}`

Eligibility check

Event	When it is sent	`payload.id` is	Fetch with
`eligibilityCheck_new`	A successful portal lookup is recorded, or an automated phone check completes with requester and service details.	Eligibility check ID	`GET /v1/eligibilityChecks/{id}`

Support case

Event	When it is sent	`payload.id` is	Fetch with
`supportCaseHistory_sentToPool`	A case is linked to a pool.	Case history entry ID	No public endpoint
`supportCaseHistory_assigned`	A case is assigned to a user.	Case history entry ID	No public endpoint
`supportCaseHistory_updated`	A note or file entry is added to a case.	Case history entry ID	No public endpoint
`supportCaseHistory_mentioned`	A new case entry mentions another user.	Case history entry ID	No public endpoint

What counts as a support case update

A note is added.
A file entry is added.
An entry with valid mentions also sends supportCaseHistory_mentioned.

Case detail edits, note deletion, unassignment, and pool removal do not send supportCaseHistory_updated.

Stop-loss filing

Event	When it is sent	`payload.id` is	Fetch with
`stoplossFiling_new`	A filing is created manually or automatically for claim review, captive coverage, or aggregate stop-loss.	Stop-loss filing ID	No public endpoint
`stoplossFiling_update`	Filing details or status change, including a Draft filing moving to Pending after submission.	Stop-loss filing ID	No public endpoint
`stoplossFiling_delete`	A stop-loss filing is about to be deleted.	Stop-loss filing ID	No public endpoint

What counts as a stop-loss filing update

Filing details are saved, such as notes, requested funds, or permitted claim and coverage links.
A filing's status is adjusted.
An Arlo submission changes a Draft filing to Pending.
An email submission changes a Draft filing to Pending.

Submission of a filing that is not Draft does not send an update from the submission step.

Accumulator rollover

Event	When it is sent	`payload.id` is	Fetch with
`submittedAccumulatorRollover_approved`	A pending accumulator credit is approved and its rollover credit is created.	Submitted rollover ID	`GET /v1/submittedAccumulator` `Rollovers/{id}`
`submittedAccumulatorRollover_rejected`	A pending accumulator credit is rejected.	Submitted rollover ID	`GET /v1/submittedAccumulator` `Rollovers/{id}`

Configuration

Add the webhook URL and select the Auth from the dropdown. To create an Auth, click the ‘Authentications’ table right above the configuration and create.

Event details

Automatic retries
Yuzu considers a delivery successful when your endpoint returns a 2xx HTTP status. For non-2xx responses or connection errors, Yuzu records the delivery as failed and retries it up to the configured maximum number of attempts. The default is three attempts.
Retries use the configured delay between attempts. The default delay is five seconds; Yuzu does not use exponential backoff. After the maximum attempts are exhausted, the delivery remains failed and is not retried automatically.

Manual retries
You can manually retry an event from its Event Details page by selecting Retry Event. A manual retry creates new delivery records and sends the same event again, including its original event ID. Previous delivery results remain available for review.

Event ordering
Yuzu does not guarantee that events are delivered in the order in which they are generated. Do not make your integration depend on a specific event sequence. Process events idempotently, use the event ID to detect repeated deliveries, and retrieve the latest resource state from the API when required.
Your endpoint should return a 2xx response only after it has accepted the event for processing. Return a non-2xx response when delivery should be retried.

When would I use a webhook?

Use a webhook if you must know when something happens in Yuzu, and you do not want to poll the API. It is also the easiest way to find out which objects are new or changed: the public API does not expose an updatedAt or lastModified field, so you cannot detect changes by polling.

How do I use a webhook?

Give Yuzu an HTTPS endpoint and an auth method (API key, basic, or bearer). You can also set a secret key.
Subscribe to the events that you want, for example Member Update.
Yuzu sends a POST to your endpoint when the event occurs. The body is small; it contains only the event ID, the event type, and the ID of the object that changed:

{ "id": "b1d92755-...", "type": "member_update", "payload": { "id": "284fd0f0-..." } }

Call the public API with that ID to get the full record, for example GET /v1/members/{memberId}.
Answer with a 2xx status code. If you do not, Yuzu tries again, up to the configured retry limit.

Notes

The webhook never contains member data. This keeps PHI out of the request body. Always fetch the object from the API.
Use the top-level event id to remove duplicates, because a retry can cause more than one delivery.
If you set a secret key, verify the X-Yuzu-Signature header. It is an HMAC-SHA256 of the request body.
Delivery is asynchronous. Expect a short delay after the change.
One event is sent for each member that changes, not one for each file. A census upload of 200 members sends 200 events.
Today, new members also arrive as Member Update, not New Member. Subscribe to Member Update if you must see new members.

Contents