> For the complete documentation index, see [llms.txt](https://docs.vcheckglobal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vcheckglobal.com/api-reference/background-check/background-check-webhooks.md). # Background Check Webhooks Register and manage webhook endpoints to receive real-time Background Check event notifications. ## Get Webhook Config > Retrieve the current webhook configuration for the account. ```json {"openapi":"3.1.0","info":{"title":"Vcheck Global API","version":"5.4.0"},"tags":[{"name":"Background Check Webhooks","description":"Register and manage webhook endpoints to receive real-time Background Check event notifications."}],"servers":[{"url":"https://api-platform.vcheckglobal.net/v2","description":"Vcheck platform (sandbox host issued first; production host after sign-off)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Obtain a token via POST https://api-platform.vcheckglobal.net/v2/oauth2/token.\nInclude in all subsequent requests as `Authorization: Bearer `.\nTokens expire after 3,600 seconds - cache and reuse; request a new one only when close to expiry.\n"}}},"paths":{"/backgroundcheck/webhook":{"get":{"tags":["Background Check Webhooks"],"operationId":"getBgcWebhook","summary":"Get Webhook Config","description":"Retrieve the current webhook configuration for the account.","responses":{"200":{"description":"Current webhook config.","content":{"application/json":{}}},"403":{"description":"Forbidden — endpoint disabled or insufficient scope.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"404":{"description":"No webhook registered for this account.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}}}}} ``` ## Register Webhook > Register an HTTPS endpoint to receive real-time Background Check event notifications.\ > VCheck posts a signed event to your callback URL each time a subscribed event occurs.\ > Respond with 2xx within 30 seconds to acknowledge delivery.\ > \ > \*\*Supported auth\_method values:\*\*\ > \ > \| auth\_method | auth\_credentials shape | What VCheck sends to your server |\ > \|---|---|---|\ > \| \`HMAC\_SHA256\` | \`{ "secret": "..." }\` | \`X-VCheck-Signature-256: sha256=\\` |\ > \| \`BEARER\_TOKEN\` | \`{ "token": "..." }\` | \`Authorization: Bearer \\` |\ > \| \`HEADER\_API\_KEY\` | \`{ "header\_name": "X-Api-Key", "key": "..." }\` | \`\: \\` |
```json {"openapi":"3.1.0","info":{"title":"Vcheck Global API","version":"5.4.0"},"tags":[{"name":"Background Check Webhooks","description":"Register and manage webhook endpoints to receive real-time Background Check event notifications."}],"servers":[{"url":"https://api-platform.vcheckglobal.net/v2","description":"Vcheck platform (sandbox host issued first; production host after sign-off)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Obtain a token via POST https://api-platform.vcheckglobal.net/v2/oauth2/token.\nInclude in all subsequent requests as `Authorization: Bearer `.\nTokens expire after 3,600 seconds - cache and reuse; request a new one only when close to expiry.\n"}},"responses":{"BadRequest":{"description":"Request body or parameters failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"schemas":{"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}}}}},"paths":{"/backgroundcheck/webhook":{"post":{"tags":["Background Check Webhooks"],"operationId":"registerBgcWebhook","summary":"Register Webhook","description":"Register an HTTPS endpoint to receive real-time Background Check event notifications.\nVCheck posts a signed event to your callback URL each time a subscribed event occurs.\nRespond with 2xx within 30 seconds to acknowledge delivery.\n\n**Supported auth_method values:**\n\n| auth_method | auth_credentials shape | What VCheck sends to your server |\n|---|---|---|\n| `HMAC_SHA256` | `{ \"secret\": \"...\" }` | `X-VCheck-Signature-256: sha256=` |\n| `BEARER_TOKEN` | `{ \"token\": \"...\" }` | `Authorization: Bearer ` |\n| `HEADER_API_KEY` | `{ \"header_name\": \"X-Api-Key\", \"key\": \"...\" }` | `: ` |\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["callback_url","auth_method","auth_credentials","event_types"],"properties":{"callback_url":{"type":"string","format":"uri","description":"Your HTTPS endpoint. Must return 2xx within 30 s."},"auth_method":{"type":"string","enum":["HMAC_SHA256","BEARER_TOKEN","HEADER_API_KEY"],"description":"How VCheck authenticates to your server."},"auth_credentials":{"type":"object","description":"Credentials object - shape depends on auth_method."},"event_types":{"type":"array","items":{"type":"string","enum":["ORDER_PLACED","STATUS_PENDING","STATUS_COMPLETED"]},"description":"Events to subscribe to."}},"additionalProperties":false}}}},"responses":{"201":{"description":"Webhook registered.","content":{"application/json":{}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"description":"Forbidden — endpoint disabled or insufficient scope.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"409":{"description":"Webhook already registered — use PATCH to update.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}}}}} ``` ## Deactivate Webhook > Permanently removes the Background Check webhook registration for this account. Event\ > delivery stops immediately; any events generated after this call will not be retried to\ > the old endpoint.\ > \ > \- After deletion, order events are queued internally until a new webhook is registered.\ > \- Re-register at any time using \`POST /backgroundcheck/webhook\`.\ > \- A 404 is returned if no webhook is currently registered.
```json {"openapi":"3.1.0","info":{"title":"Vcheck Global API","version":"5.4.0"},"tags":[{"name":"Background Check Webhooks","description":"Register and manage webhook endpoints to receive real-time Background Check event notifications."}],"servers":[{"url":"https://api-platform.vcheckglobal.net/v2","description":"Vcheck platform (sandbox host issued first; production host after sign-off)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Obtain a token via POST https://api-platform.vcheckglobal.net/v2/oauth2/token.\nInclude in all subsequent requests as `Authorization: Bearer `.\nTokens expire after 3,600 seconds - cache and reuse; request a new one only when close to expiry.\n"}}},"paths":{"/backgroundcheck/webhook":{"delete":{"tags":["Background Check Webhooks"],"operationId":"deleteBgcWebhook","summary":"Deactivate Webhook","description":"Permanently removes the Background Check webhook registration for this account. Event\ndelivery stops immediately; any events generated after this call will not be retried to\nthe old endpoint.\n\n- After deletion, order events are queued internally until a new webhook is registered.\n- Re-register at any time using `POST /backgroundcheck/webhook`.\n- A 404 is returned if no webhook is currently registered.\n","responses":{"200":{"description":"Webhook deactivated.","content":{"application/json":{}}},"403":{"description":"Forbidden — endpoint disabled or insufficient scope.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"404":{"description":"No webhook registered.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}}}}} ``` ## Update Webhook > Updates one or more fields of the registered Background Check webhook. Only the fields\ > included in the request body are modified; all other settings remain unchanged.\ > \ > \- \`callback\_url\` - replace the delivery endpoint with a new HTTPS URL.\ > \- \`auth\_method\` - if changed, \`auth\_credentials\` must also be provided to supply the\ > new credentials for the chosen method.\ > \- \`auth\_credentials\` - credentials object matching the current (or updated) \`auth\_method\`.\ > \- \`event\_types\` - replaces the existing list in full; include all event types you want\ > active (\`ORDER\_PLACED\`, \`STATUS\_PENDING\`, \`STATUS\_COMPLETED\`), not just the ones being added.\ > \- A 404 is returned if no webhook has been registered yet; call POST first.
```json {"openapi":"3.1.0","info":{"title":"Vcheck Global API","version":"5.4.0"},"tags":[{"name":"Background Check Webhooks","description":"Register and manage webhook endpoints to receive real-time Background Check event notifications."}],"servers":[{"url":"https://api-platform.vcheckglobal.net/v2","description":"Vcheck platform (sandbox host issued first; production host after sign-off)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Obtain a token via POST https://api-platform.vcheckglobal.net/v2/oauth2/token.\nInclude in all subsequent requests as `Authorization: Bearer `.\nTokens expire after 3,600 seconds - cache and reuse; request a new one only when close to expiry.\n"}}},"paths":{"/backgroundcheck/webhook":{"patch":{"tags":["Background Check Webhooks"],"operationId":"updateBgcWebhook","summary":"Update Webhook","description":"Updates one or more fields of the registered Background Check webhook. Only the fields\nincluded in the request body are modified; all other settings remain unchanged.\n\n- `callback_url` - replace the delivery endpoint with a new HTTPS URL.\n- `auth_method` - if changed, `auth_credentials` must also be provided to supply the\n new credentials for the chosen method.\n- `auth_credentials` - credentials object matching the current (or updated) `auth_method`.\n- `event_types` - replaces the existing list in full; include all event types you want\n active (`ORDER_PLACED`, `STATUS_PENDING`, `STATUS_COMPLETED`), not just the ones being added.\n- A 404 is returned if no webhook has been registered yet; call POST first.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"callback_url":{"type":"string","format":"uri"},"auth_method":{"type":"string","enum":["HMAC_SHA256","BEARER_TOKEN","HEADER_API_KEY"]},"auth_credentials":{"type":"object"},"event_types":{"type":"array","items":{"type":"string","enum":["ORDER_PLACED","STATUS_PENDING","STATUS_COMPLETED"]}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Webhook updated.","content":{"application/json":{}}},"403":{"description":"Forbidden — endpoint disabled or insufficient scope.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"404":{"description":"No webhook registered.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}}}}} ``` {% openapi-webhook spec="vcheck-api" name="bgc-order-placed" method="post" %} [vcheck-api](https://4401d86825a13bf607936cc3a9f3897a.r2.cloudflarestorage.com/gitbook-x-prod-openapi/raw/a5b7db1763aa91d87de1c4a178589e9042c10ea5aea821f0d748c0db2666166b.yaml?X-Amz-Algorithm=AWS4-HMAC-SHA256\&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD\&X-Amz-Credential=dce48141f43c0191a2ad043a6888781c%2F20261027%2Fauto%2Fs3%2Faws4_request\&X-Amz-Date=20261027T023517Z\&X-Amz-Expires=172800\&X-Amz-Signature=9e38bbb1919e8945b4feb4403f338742201c979ab51ac9645e8804323b0145bb\&X-Amz-SignedHeaders=host\&x-amz-checksum-mode=ENABLED\&x-id=GetObject) {% endopenapi-webhook %} {% openapi-webhook spec="vcheck-api" name="bgc-status-pending" method="post" %} [vcheck-api](https://4401d86825a13bf607936cc3a9f3897a.r2.cloudflarestorage.com/gitbook-x-prod-openapi/raw/a5b7db1763aa91d87de1c4a178589e9042c10ea5aea821f0d748c0db2666166b.yaml?X-Amz-Algorithm=AWS4-HMAC-SHA256\&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD\&X-Amz-Credential=dce48141f43c0191a2ad043a6888781c%2F20261027%2Fauto%2Fs3%2Faws4_request\&X-Amz-Date=20261027T023517Z\&X-Amz-Expires=172800\&X-Amz-Signature=9e38bbb1919e8945b4feb4403f338742201c979ab51ac9645e8804323b0145bb\&X-Amz-SignedHeaders=host\&x-amz-checksum-mode=ENABLED\&x-id=GetObject) {% endopenapi-webhook %} {% openapi-webhook spec="vcheck-api" name="bgc-status-completed" method="post" %} [vcheck-api](https://4401d86825a13bf607936cc3a9f3897a.r2.cloudflarestorage.com/gitbook-x-prod-openapi/raw/a5b7db1763aa91d87de1c4a178589e9042c10ea5aea821f0d748c0db2666166b.yaml?X-Amz-Algorithm=AWS4-HMAC-SHA256\&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD\&X-Amz-Credential=dce48141f43c0191a2ad043a6888781c%2F20261027%2Fauto%2Fs3%2Faws4_request\&X-Amz-Date=20261027T023517Z\&X-Amz-Expires=172800\&X-Amz-Signature=9e38bbb1919e8945b4feb4403f338742201c979ab51ac9645e8804323b0145bb\&X-Amz-SignedHeaders=host\&x-amz-checksum-mode=ENABLED\&x-id=GetObject) {% endopenapi-webhook %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.vcheckglobal.com/api-reference/background-check/background-check-webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.