GuidesAPI ReferenceChangelog
Log In

Document webhook events will notify you when a new, user-uploaded document is available for a user. The payload contains metadata about the document, not the data itself. After receiving a webhook event, call the corresponding endpoint to retrieve the document data.


A new, user-uploaded document is available. Use end_user_id and document_id in the payload to query the GET Document to fetch the document data.

The webhook event will be sent for all documents that the user has successfully uploaded to Pinwheel.

If the document didn't pass the anti-virus scan, we'll indicate this within the webhook using the error_code.

Payload Schema

Payload ParamTypeDescription
end_user_idstringThe user identifier you provided in the link token to connect the account.
document_idstringUUID of the document.
namestringName of the job, which is document_uploads.
timestampstringISO 8601 timestamp of job completion.
outcomestringThe outcome of the job, either success, error, or pending. If pending you will receive another webhook with outcome as success or error within 24 hours.
link_token_idstringUUID of Link token used to initialize Link.
paramsobjectParameters of the job, if applicable.
params.document_typestringClassification of the document (e.g. paystub, w2, 1099).
error_codestringOn error, a string describing the error.
error_typestringOn error, a high level classification of the error.
idstringUUID of the job.

We may add additional document_types without releasing a new API version. Make sure to handle a default other case if parsing these as enums. We may also add additional params for specific document types that provide metadata to help you decide if you want to retrieve the document (e.g. year for tax forms, pay date for paystubs).

Sample Webhook Event

  "event_id": "641da69f-3c2d-4ebd-bbaa-42b2147c89ba",
  "event": "documents.added",
  "payload": {
    "document_id": "b90e9fc9-c1ce-42d0-9bde-a08c728e2683",
    "id": "d9617def-0221-4edf-aa0e-7a7f63748cbb",
    "name": "document_uploads",
    "timestamp": "2023-06-09T21:23:03.437394+00:00",
    "outcome": "success",
    "link_token_id": "c10ab8f6-4866-4f6d-b642-ffad6899249e",
    "end_user_id": "12345678",
      "document_type": "paystub",
    "error_code": null,
    "error_type": null