Setting up webhooks

The webhook feature allows you to be notified automatically when specific events occur during a consumer's verification process.

Below is a list of the available notifiers you can set up, and their use cases:

• Eligible - when a verification is approved
  • notifierEventType: SUCCESS
  • Use - applying discounts to a logged-in consumer's user account and knowing when to prompt consumers to begin the verification process
• Document Rejected - when a consumer's uploaded document has been rejected
  • notifierEventType: DOCUMENT_REJECTED
  • Use - cases where metrics are collected to determine drop-off
• Max Attempts - when a consumer has reached the maximum number of attempts to prove eligibility
  • notifierEventType: MAX_DOC_UPLOAD_ATTEMPTS
  • Use - when there are benefits in noting a user's ineligibility to an account, like determining whether to prompt them for verification in the future
• Reminder to complete verification - when a consumer needs to finish an incomplete request
  • notifierEventType: REMINDER
  • Use - cases where more than a SheerID automated reminder email would benefit, such as a prompt or alert on the site that points out that the user has a verification in progress they haven't completed
• Consolation - when a consumer is found to be ineligible, but is offered a consolation
  • notifierEventType: CONSOLATION
  • Use - cases where there is an alternative offer available for users that don't require verification
• Email Loop - when a consumer is sent an email to verify ownership of their email address
  • notifierEventType: EMAIL_LOOP
  • Use - cases where having a valid and current email address is paramount for users
• Expiration - when a consumer's verification request has expired
  • notifierEventType: EXPIRATION
  • Use - cases where metrics on user drop-off are strongly desired (as expirations only occur if a user has started a verification process but has not completed it after 7 days — note that enabling this webhook will result in a lot of noise, as every verificationId generated will expire and users can create a countless number of them)
• Error - when an error occurs during the consumer's verification process
  • notifierEventType: ERROR
  • Use - taking action with users who encounter blockers when trying to verify and diagnosing potential issues

How to set up webhooks in MySheerID

1. Login to your MySheerID account with the Program Admin user permissions
2. Navigate to the Program section and select the program you want to update
3. Select the Settings button in the first section of the Program page
4. Scroll down to the Webhooks section and click +Add to make a pop-up appear
5. To enable webhooks you'll need to toggle the switch from Off to On, then input your endpoint URL in the available field
6. Under the list of Verification events, you can toggle on any of the events that would be beneficial to you and your team
7. Click Save to begin testing and using webhooks

Deprecated webhooks

For those using the older webhook feature, you will see the following:

While the deprecated webhook setting is still functional, it will no longer be updated and eventually be phased out of the platform.

We recommend disabling the deprecated webhook setting and transitioning to the new webhook feature as soon as possible.

Notes

• The webhook will send a POST message in JSON format. Included in the payload is the verificationId. SheerID never sends consumer personally identifiable information (PII) in a webhook payload.

Example payload

• You can use the verificationId to retrieve all user and program details about a verification from SheerID's REST APIs.
• To ensure a consistent and predictable experience, any changes you make to your verification settings (e.g., Program configurations) will only apply to new verifications. Verifications that are already in progress will not be disrupted and will be completed using the settings that were active when they began.

• 

  As a MySheerID Account Owner with the API Access permission, you can find your access tokens in the MySheerID portal. This includes your Secret Token, which can be used to validate the HMAC signature sent in the headers of the webhook payloads. This token is account-scoped, so it applies to all webhooks across every program in your account.

Best practices for when webhooks should fire vary based on the use case desired:

• If you are using webhooks for CRM integration (storing all zero party consumer data), webhooks should be fired upon success, max failure (when a user tries to verify via document review 3x and fails), and expired verification.
• If you are looking to simply link accounts to a successful verification (account linking reward methodology), webhooks should be fired on success only.
• If you are hosting your own emails, then webhooks should be fired on all emailable events. For information on emailable events, see this article.