Webhooks notify your system automatically when specific events occur during a consumer verification process. To set up an account tagging strategy successfully, use webhooks to receive alerts for successful verification events, then pull the necessary data from our REST API.
Set up webhooks when building your program
You'll be prompted configure webhooks during program creation, but if you aren't ready for this step you can return after the program has been created to make adjustments.
-
Locate the Offer Delivery section in MySheerID's program builder
- Select Account Tagging to reveal the Webhooks setting
-
Click +Add on the Webhooks card to open the configuration dialog box
- Toggle the switch to On, then input your endpoint URL
- Under the list of Verification events, toggle on the specific events that serve your business goals, then click Save to complete the process and begin testing
You can also access Webhook settings in the complete list of MySheerID Settings.
Best practices for webhook triggers
The ideal events to activate depend entirely on your specific system integration.
- Account tagging: If you only need to link a customer account to a successful verification, activate the webhook for success only
- CRM integration: If you use webhooks to populate a CRM and store all zero-party consumer data, activate webhooks for success, max failure (when a user fails document review three times), and expired verification
- Self-hosted emails: If you host your own email communications rather than using SheerID automated messages, activate webhooks for all emailable events
Available webhook events
Below are the notifiers you can activate within your account alongside their common use cases.
| Webhook event | Notifier event type | Use case |
| Add School Request when an add school request has been rejected or when a requested school has been added to SheerID's global organization list |
ADD_SCHOOL_REQUEST | Tracking manual requests from students or educators who cannot find their specific institution in the standard dropdown list. For step-by-step instructions on querying endpoints and processing these outcomes, see the handling guide below. |
|
Consolation when a consumer is found to be ineligible, but is offered a consolation |
CONSOLATION | Providing an alternative, less restrictive offer to users who do not successfully pass the verification check. |
|
Document Rejected when a consumer's uploaded document has been rejected |
DOCUMENT_REJECTED | Gathering system metrics to evaluate user drop-off points during document review. |
|
Eligible when a verification is approved |
SUCCESS | Applying discounts directly to a logged-in user account and tracking when to reward the consumer. |
|
Email Loop when a consumer is sent an email to verify ownership of their email address |
EMAIL_LOOP | Verifying active ownership of an email address when a current, valid email is mandatory for account security. |
|
Error when an error occurs during the consumer's verification process |
ERROR | Diagnosing potential technical issues and assisting users who encounter unexpected blockers during verification. |
|
Expiration when a consumer's verification request has expired |
EXPIRATION | Analyzing drop-off metrics. Expirations occur only if a user starts verification but does not finish within 7 days. Activating this webhook can result in significant data volume since every generated verification ID eventually expires. |
|
Max Attempts when a consumer has reached the maximum number of attempts to prove eligibility |
MAX_DOC_UPLOAD_ATTEMPTS | Noting user ineligibility on their profile so your system knows whether to block future verification prompts. |
|
Reminder to complete verification when a consumer needs to finish an incomplete request |
REMINDER | Triggering custom on-site alerts or banners to remind a user that they have an incomplete verification in progress. |
Technical specifications and security
The webhook engine transmits a POST request in JSON format. This payload includes a unique verificationId and a notifierEventType. SheerID never transmits consumer personally identifiable information (PII) within a webhook payload.
Example payload reference
You can use the transmitted verificationId to safely query all user and program details from the SheerID REST API.
To ensure a consistent and predictable integration experience, any changes you make to your program configurations will only apply to new verification sessions. Verification sessions already in progress will complete normally using the exact rules that were active when the session began.
As a MySheerID Account Owner with the API Access permission, you can view your security credentials inside the portal. This includes your Secret Token, which allows your server to validate the HMAC signature sent in the headers of each webhook payload. This token is scoped to your entire account and applies to all active programs.
Delivery retry schedule
If the SheerID engine does not receive an HTTP status 2xx success code from your endpoint, it considers the delivery a failure and resends the payload according to the following schedule:
| Failed attempt | Will retry after |
| 1 | immediately |
| 2 | 1 hour |
| 3 | 3 hours |
| 4 | 7 hours |
If the system cannot deliver the notification after the fourth attempt, the message is marked as permanently failed and no further attempts occur.
Handling Add School Request webhooks
The Add School Request (ASR) webhook notifies your system about the final status of an institution validation review. Your endpoint will receive a POST request with one of two potential event types signaling either success or failure. Handling this workflow requires extracting the tracking data from the payload, querying the SheerID /details endpoint, and interpreting the final organization decision.
Webhook request body structure
The incoming payload contains a specific tracking ID and the basic event outcome.
| Property | Type | Description |
| verificationId | String | A unique identifier for the specific Add School Request. This ID is required for the /details endpoint. |
| notifierEventType | String | The outcome of the ASR process, which will read either ADD_SCHOOL_SUCCESS or ADD_SCHOOL_FAILURE. |
Success example payload
Failure example payload
Querying the details endpoint
Upon receiving the webhook notification, your system must use the provided verificationId to call the details endpoint (/details) to fetch the full context and decision for the ASR.
- Method: GET (or as required by your service)
- URL: http://services.sheerid.com/rest/v2/verification/{verificationId}/details
For complete parameter specifications, review the SheerID REST API Reference.
Interpreting the API response
The response from the /details endpoint will contain the complete ASR context inside the personInfo object. This structure contains the original data submitted by the user alongside the final system decision.
Key data properties
- personInfo.metadata: Object containing the final decision, internal organization tracking numbers, and approval timestamps
- personInfo.firstName, personInfo.lastName, personInfo.email: The contact details provided by the applicant who submitted the request
-
organization: Object containing the specific organization name text originally typed by the user. The value for the organization.id in this context will always be 0
Decision values within personInfo.metadata
Review the core fields within the metadata object to determine exactly how the request was resolved.
| Property | Description | Possible values |
| addSchoolRequestDecision | The final system decision. This is the primary field to evaluate for ASR outcome. |
ADDED (Success) ALREADY_EXISTS (Duplicate) REJECTED (Denied) |
| addSchoolRequestOrgId | The Org ID of the organization that was newly created or found to be a pre-existing duplicate. |
"{found duplicate or created org id}" This property returns empty if the request is rejected. |
| addSchoolRequestCompletionTimestamp | The exact UNIX timestamp recording when the manual review process was finalized. | "{Unix timestamp}" |
| addSchoolRequestOrgName | The final name of the organization within the database. |
"{SheerID org name}" This property returns empty if the request is rejected. |
| addSchoolRequestOrgType | The SheerID organization type. |
"{SheerID org type}" This property returns empty if the request is rejected. |
| addSchoolRequestSubmittedWebsite | The specific web URL supplied by the user during their initial application. | "{ASR submitted website}" |
| addSchoolRequestOrgEmailDomains | The email domains associated with the final organization. |
"{domain 1},{domain 2}" This property returns empty if the request is rejected. |
Mapping outcomes to system actions
The combination of the initial event type and the subsequent metadata decision dictates how your system should update the user profile or interface.
| Initial notifierEventType | addSchoolRequestDecision | Definition & required action |
| ADD_SCHOOL_SUCCESS | ADDED | A new school or organization was successfully validated and added to the database. |
| ADD_SCHOOL_FAILURE | ALREADY_EXISTS | An organization matching the submitted details (e.g. website/name) was found to be an existing organization within the database. |
| ADD_SCHOOL_FAILURE | REJECTED | The submitted institution did not meet eligibility requirements and was denied. |
Overview for ASR webhook processing
To build out your automated handler, structure your code logic around these four sequential operations:
- Receive webhook POST request
- Extract verificationId
- Call /details to retrieve full request data
- Examine the value of personInfo.metadata.addSchoolRequestDecision
- If ADDED: Process as a Successful addition
- If ALREADY_EXISTS: Process as a Failed addition due to duplication
- If REJECTED: Process as a Failed addition due to rejection