Webhook Events

Earnings Stream webhook events will notify you when a newer version of the Earnings Stream is available for a user.

earnings_stream.payouts.refreshed

Payouts for a user's earnings stream have been refreshed. Use end_user_id in the payload to query the GET /v1/end_users/{id}/earnings_stream/payouts to fetch the most up-to-date payouts data.

We’ll send this webhook event:

After your user connects an account with Link or performs an On Demand Update
Whenever Monitoring detects a change to the underlying information in Earnings Stream.

The webhook event will include metadata about the Earnings Stream, indicating which components are available or unavailable. If unavailable it will include an unavailable_reason summarizing why.

Payload Schema

Payload Param	Type	Description
`end_user_id`	string	The user identifier you provided in the link token to connect the account.
`refreshed_at`	string	ISO 8601 timestamp of when the data underlying the earnings stream was most recently checked for changes.
`updated_at`	string	ISO 8601 timestamp of when the earnings stream most recently had a data change (e.g., the user worked another shift so a new accrued earning was recorded).
`availability`	object	See child attributes for details.
`availability.payouts_estimated`	object	See child attributes for details.
`availability.payouts_estimated.earnings_accrued`	object	Availability of accrued earnings for estimated payouts. See Availability Schema below for object structure.
`availability.payouts_processed`	object	See child attributes for details.
`availability.payouts_processed.earnings_accrued`	object	Availability of accrued earnings for processed payouts. See Availability Schema below for object structure.
`availability.payouts_processed.earnings_unknown`	object	Availability of unknown earnings for processed payouts. See Availability Schema below for object structure.

Availability Schema

Parameter	Type	Description
status	string	Either `available`, if the class of data is present in the Earnings Stream, or `unavailable`, if the data can not be included.
unavailable_reason (optional)	string	On `unavailable`, provides an explanation for why the data is not present. See the table below for possible values. `null` if `status = available`.

Unavailable Reasons

Unavailable Reason	Description
`temporary_outage`	There was a problem with retrieving data from the payroll platform, but this is temporary and should resolve on its own. Try again later.
`user_action.waiting_for_work`	The user has paystubs but no shifts yet for the current pay period. Once the user works a shift, a payout should become available.
`user_action.new_employee`	The user does not yet have any paystubs or shifts, but we know their employment began recently. Once the user works a shift, a payout may become available.
`user_action.undetermined`	The user's platform does not yet have any data. This may be because they need to work a shift, or the platform may not provide the data.
`employer_not_supported`	The platform for the end-user's employer does not provide the necessary data.

We may add additional unavailable reasons without releasing a new API version. Make sure to handle a default other case if parsing these as enums.

Sample Webhook Event

{
    "event": "earnings_stream.payouts.refreshed",
    "event_id": "e9d5660b-52cc-4b66-adba-67eed17447fe",
    "payload": {
        "end_user_id": "my_user_12345",
        "updated_at": "2022-01-01T00:00:00+0000",
        "refreshed_at": "2022-01-02T00:00:00+0000",
        "availability": {
            "payouts_estimated": {"earnings_accrued": {"status": "available", "unavailable_reason": null}},
            "payouts_processed": {
                "earnings_accrued": {"status": "available", "unavailable_reason": null},
                "earnings_unknown": {"status": "available", "unavailable_reason": null},
            },
        },
    }
}

Please contact [email protected] for access to our Developer Dashboard.