GuidesAPI ReferenceChangelog
Log In

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


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 ParamTypeDescription
end_user_idstringThe user identifier you provided in the link token to connect the account.
refreshed_atstringISO 8601 timestamp of when the data underlying the earnings stream was most recently checked for changes.
updated_atstringISO 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).
availabilityobjectSee child attributes for details.
availability.payouts_estimatedobjectSee child attributes for details.
availability.payouts_estimated.earnings_accruedobjectAvailability of accrued earnings for estimated payouts. See Availability Schema below for object structure.
availability.payouts_processedobjectSee child attributes for details.
availability.payouts_processed.earnings_accruedobjectAvailability of accrued earnings for processed payouts. See Availability Schema below for object structure.
availability.payouts_processed.earnings_unknownobjectAvailability of unknown earnings for processed payouts. See Availability Schema below for object structure.
Availability Schema
statusstringEither available, if the class of data is present in the Earnings Stream, or unavailable, if the data can not be included.
unavailable_reason (optional)stringOn 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 ReasonDescription
temporary_outageThere 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_workThe 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_employeeThe 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.undeterminedThe 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_supportedThe 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},