Sample - Plaid API
POST/sandbox/income/fire_webhook

Trigger an Income webhook

Triggers a simulated Payroll or Document Income webhook in the Sandbox environment. Supply item_id, webhook, and webhook_code, and optionally provide verification_status and the applicable user identifier. The webhook is sent to the specified URL.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

7 body fields

Sandbox webhook simulation details, including the target URL and webhook event to send.

client_idstringoptional
Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.
secretstringoptional
Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body.
item_idstringrequired
The Item ID associated with the verification.
user_idstringoptional
The user identifier to include in the test webhook. For `USER_INCOME_VERIFICATION` and `USER_INCOME_VERIFICATION_RISK_SIGNALS`, use the `user_id` returned by `/user/create`, which begins with `usr_`. For `INCOME_VERIFICATION` and `INCOME_VERIFICATION_RISK_SIGNALS`, use the legacy webhook `user_id` associated with the user token.
webhookstringrequired
The URL to which the webhook should be sent.
verification_statusstringoptional
`VERIFICATION_STATUS_PROCESSING_COMPLETE`: The income verification status processing has completed. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the `/income/verification/paystubs/get` endpoint and check the document metadata to see which documents were successfully parsed. `VERIFICATION_STATUS_PROCESSING_FAILED`: A failure occurred when attempting to process the verification documentation. `VERIFICATION_STATUS_PENDING_APPROVAL`: (deprecated) The income verification has been sent to the user for review.
Allowed:VERIFICATION_STATUS_PROCESSING_COMPLETEVERIFICATION_STATUS_PROCESSING_FAILEDVERIFICATION_STATUS_PENDING_APPROVAL
webhook_codestringrequired
The webhook codes that can be fired by this test endpoint.
Allowed:INCOME_VERIFICATIONUSER_INCOME_VERIFICATIONINCOME_VERIFICATION_RISK_SIGNALSUSER_INCOME_VERIFICATION_RISK_SIGNALS

2 status codes
200Returns a `request_id` that uniquely identifies the webhook simulation request.
request_idstringrequired
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
defaultReturned when the request cannot be processed; inspect `error_code`, `error_type`, and `error_message` to identify the problem.
error_typestringrequired
A broad categorization of the error. Safe for programmatic use.
Allowed:INVALID_REQUESTINVALID_RESULTINVALID_INPUTINSTITUTION_ERRORRATE_LIMIT_EXCEEDEDAPI_ERRORITEM_ERRORASSET_REPORT_ERRORBASE_REPORT_ERRORRECAPTCHA_ERROROAUTH_ERRORPAYMENT_ERROR
error_codestringrequired
The particular error code. Safe for programmatic use.
error_code_reasonstringoptional
The specific reason for the error code. Currently, reasons are only supported for OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user's OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user's OAuth connection to this institution is invalid because the user revoked their connection.
error_messagestringrequired
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_messagestringrequired
A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use.
request_idstringoptional
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causesarrayoptional
In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object.
statusintegeroptional
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_urlstringoptional
The URL of a Plaid documentation page with more information about the error
suggested_actionstringoptional
Suggested steps for resolving the error
required_account_subtypesarray<string>optional
A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.
provided_account_subtypesarray<string>optional
A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product.

Error handling

item_id, webhook, and webhook_code are required. webhook must be a URL, and webhook_code must be one of INCOME_VERIFICATION, USER_INCOME_VERIFICATION, INCOME_VERIFICATION_RISK_SIGNALS, or USER_INCOME_VERIFICATION_RISK_SIGNALS. If supplied, verification_status must be VERIFICATION_STATUS_PROCESSING_COMPLETE, VERIFICATION_STATUS_PROCESSING_FAILED, or VERIFICATION_STATUS_PENDING_APPROVAL.