Webhook Subscriptions — Receive BGV Reports Automatically
A webhook subscription sends each finished background verification straight to your own system, with a link to the PDF report — so nobody has to download reports from the portal or ask SpringVerify to send them.
Before you start
Ask your IT team for two things.
- The address that will receive reports. It must be a full web address starting with https, such as https://your-system.example.com/springverify. Addresses inside your private network do not work, because our servers must be able to reach them over the internet.
- How we should prove it is us. Your IT team picks one of the options in the table below and gives you the matching details.
Option in the portal | What your IT team gives you |
None | Nothing |
Basic | A username and password |
Bearer token | A token |
API key header | A header name (for example X-Api-Key) and the key |
HMAC signature | A signing secret, and optionally the header name (default X-SpringVerify-Signature) |
You can add up to 10 addresses per company. Each one receives every report.
Set it up
Any admin with access to the Integrations page can do this in a few minutes.
- In the SpringVerify portal, open Integrations and choose the Webhook Subscription card.
Integrations page — the Webhook Subscription card
- Click Add endpoint.
Webhook Subscription page before any address is added
- Paste the address into Endpoint URL.
- Pick the option under Authentication and enter the details your IT team gave you.
- Enable the Interim Status Updates toggle if you want updates while a verification is still in progress. (Optional)
- Click Save. The address appears in the list as Active.
- Click Send test. Your system receives a sample report for a made-up "Test Candidate". Ask your IT team to confirm it arrived.
Passwords, tokens and secrets are hidden once saved. To change one, click Edit and type the new value. Leave the field blank to keep the saved one. If you change the address, enter the secret again.
SpringVerify support can also set this up for you from our side.
When reports are sent
SpringVerify checks for newly finished verifications every 3 hours and sends them in one go. A report that finishes just after a check arrives at the next one, up to 3 hours later.
- Which reports: candidates whose verification ends as Verified or Unable to Verify. If you also want updates while a verification is still in progress, Enable interim status updates on..
- Each report is sent once to each address. A report that fails to send is tried again at the next check.
Send a report right now
On the Webhook Subscription page, find the address and click Push report.
- Enter up to 10 SV IDs, separated by commas, spaces or new lines. The SV ID is the number shown for each candidate on the Candidates page, and at the end of the candidate's page address (candidateId=...).
- Click Push report and wait. It can take up to about 45 seconds.
- Read the result for each candidate.
Result | What it means | What to do |
Sent | Your system accepted the report | Nothing |
Failed | Your system refused it or could not be reached. The Reason column says which | Share the reason with your IT team, then try again |
Skipped | The SV ID is not in your company, or the verification is not finished yet | Check the SV ID and the candidate's status |
Not attempted | Nothing was sent for this one: time ran out, or your system had already refused an earlier candidate in the same push | Read the reason, fix it if needed, then push again |
Your system sees these as resends,so it can tell them apart from first-time reports. If the PDF could not be created, your system gets a link to the report page instead, and the result says so.
To protect your system, each address accepts one push a minute, and each company 20 pushes an hour. A disabled address cannot be pushed to until its details are fixed and saved.
What your system receives
Each report arrives as one message with the candidate's details, the outcome and a link to the PDF. Your IT team can use the sample below.
Field | Meaning |
event | completed for a finished verification, status_update for an in-progress update, test for a Send test |
candidate_id | The SV ID |
overall_status, overall_status_code | completed (1) or Completed with exception (6), which is Unable to Verify |
name, email, employee_id | The candidate as entered in SpringVerify |
report_url | A link to download the PDF report. Save the PDF when it arrives rather than keeping only the link |
completed_date | When the verification finished. Empty for in-progress updates |
meta_data | Any reference details you sent when adding the candidate |
is_resend | Present and true only when someone used Push report |
{
"event": "completed",
"candidate_id": 123456,
"candidate_uuid": "9b1c2d3e-0000-0000-0000-000000000000",
"overall_status": "completed",
"overall_status_code": 1,
"name": "Asha Rao",
"email": "asha.rao@example.com",
"employee_id": "EMP-1042",
"report_url": "https://...",
"completed_date": "2026-10-12T09:30:00.000Z",
"meta_data": { "requisition_id": "REQ-77" }
}
Your system should reply with a success code (200, 201, 202 or 204) within 30 seconds. Any other reply counts as a failure, and we try again at the next check. If you chose HMAC signature, the signature header carries an HMAC-SHA256 of the exact message body, in hex, made with your signing secret.
Troubleshooting
Most problems come down to the address, the login details, or timing.
What you see | Why | What to do |
"webhook_url is not allowed" when saving | The address is private, internal, or not https | Use a public https address |
Address shows "Disabled: receiver rejected our credentials" | Your system refused our login details, so we stopped sending to that address. Your other addresses keep working | Get the correct details from IT, click Edit, enter them and Save. That turns it back on |
A finished report has not arrived | Reports go out every 3 hours, so it may simply not be time yet | Wait for the next check, or use Push report once it is live |
A report never arrives | The candidate may not be finished, or your system keeps refusing it | Check the candidate's status, then use Send test to check your system |
Push report says "Too many pushes" | The limit is one push a minute per address | Wait a minute and try again |
"The request did not finish" after Push report | Some reports may already have gone out | Push again. Resending is safe |
Your system got a page link instead of a PDF | The PDF could not be created at that moment | Push the report again later |
Redirect errors | We do not follow redirects | Use the final address your system answers on |