Handle verification outcomes
Listen for verification results so your integration can automatically trigger reactions.
You wrote code to display a modal to collect identity documents. Now, when your user submits a document, you can listen to verification results to trigger reactions in your application.
In this guide, you’ll learn how to:
- Receive an event notification when a verification finishes processing.
- Handle successful and failed verification checks.
- Turn your event handler on in production.
Verification checks are asynchronous, which means that verification results aren’t immediately available. When the processing completes, the VerificationSession status updates and the verified information is available. Stripe generates events every time a session changes status. In this guide, we’ll implement webhooks to notify your app when verification results become available.
See How sessions work to learn the status and lifecycle of verification sessions.
Set up StripeServer-side
Install our official libraries for access to the Stripe API from your application:
Create a webhook and handle VerificationSession eventsServer-side
A webhook is an endpoint on your server that receives requests from Stripe, notifying you about events that happen on your account. In this step, we’ll build an endpoint to receive events on VerificationSession status changes.
Webhook endpoints must be publicly accessible so Stripe can send unauthenticated requests. You’ll need to verify that Stripe sent the event by using the Stripe library and request header:
Now that you have the basic structure and security in place to listen to notifications from Stripe, update your webhook endpoint to handle verification session events.
All session events include the VerificationSession object, which contains details about the verification checks performed. See Accessing verification results to learn how to retrieve verified information not included in session events.
Stripe sends the following events when the session status changes:
Event name | Description | Next steps |
---|---|---|
identity.verification_session.verified | Processing of all the verification checks have completed, and they’re all successfully verified. | Trigger relevant actions in your application. |
identity.verification_session.requires_input | Processing of all the verification checks have completed, and at least one of the checks failed. | Trigger relevant actions in your application and potentially allow your user to retry the verification. |
Your webhook code needs to handle the identity.
and identity.
events. You can subscribe to other session events to trigger additional reactions in your app.
Handle VerificationSession verified status change
The identity.
event is sent when verification checks have completed and are all successfully verified.
Add code to your event handler to handle all verification checks passing:
When handling this event, you might also consider:
- Saving the verification status in your own database
- Sending an email to your user letting them know they’ve been verified
- Expanding the VerificationSession verified outputs and comparing them against an expected value.
Handle VerificationSession requires_input status changes
The identity.
event is sent when at least one of the checks failed. You can inspect the last_error hash on the verification session to handle specific failure reasons:
- The last_error.code field can be used to programmatically handle verification failures.
- The last_error.reason field contains a descriptive message explaining the failure reason and can be shown to your user.
Event error codes
Add code to your event handler to handle verification check failure:
Depending on your use case, you might want to allow your users to retry the verification if it fails. We recommend that you limit the amount of submission attempts.
When handling this event, you might also consider:
- Manually reviewing the collected information
- Sending an email to your user letting them know that their verification failed
- Providing your user an alternative verification method
Go live in production
After you’ve deployed your event handler endpoint to production, set up the endpoint so Stripe knows where to send live mode events. It’s also helpful to go through the development checklist to ensure a smooth transition when taking your integration live.
Webhook endpoints are configured in the Dashboard or programmatically using the API.
Add an endpoint in the Dashboard
In the Dashboard’s Webhooks settings page, click Add an endpoint to add a new webhook endpoint. Enter the URL of your webhook endpoint and select which events to listen to. See the full list of Verification Session events.
Add endpoint with the API
You can also programmatically create webhook endpoints. As with the form in the Dashboard, you can enter any URL as the destination for events and which event types to subscribe to.
curl https://api.stripe.com/v1/webhook_endpoints \ -u
: \ -d "url"="https://{{DOMAIN}}/my/webhook/endpoint" \ -d "enabled_events[]"="identity.verification_session.verified" \ -d "enabled_events[]"="identity.verification_session.requires_input"sk_test_4eC39HqLyjWDarjtT1zdp7dc