Documents Webhook Events

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.

documents.added

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 Param	Type	Description
`end_user_id`	string	The user identifier you provided in the link token to connect the account.
`document_id`	string	UUID of the document.
`name`	string	Name of the job, which is `document_uploads`.
`timestamp`	string	ISO 8601 timestamp of job completion.
`outcome`	string	The 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_id`	string	UUID of Link token used to initialize Link.
`params`	object	Parameters of the job, if applicable.
`params.document_type`	string	Classification of the document (e.g. paystub, w2, 1099).
`error_code`	string	On error, a string describing the error.
`error_type`	string	On error, a high level classification of the error.
`id`	string	UUID 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",
    "params":{
      "document_type": "paystub",
    },
    "error_code": null,
    "error_type": null
  }
}