Webhooks


With webhooks you can get the latest details about your orders as they happen. All you need to do is provide a value URL and you will recieve updates when:

  • Checks are completed or cancelled
  • Orders are completed or cancelled
  • The candidate has submitted their form
  • The candidate's identity has been confirmed for criminal record checks

Currently it is not possible to unsubscribe from webhook events, this functionality is coming soon. We will also introduce more event types to keep you in control of your data.

Manage webhooks in the Verifile portal

You can manage your webhook subscriptions in the Verifile portal. After you log in, click My Account and then select the nofifications tab.

From this page, you can view your subscribed webhooks and your webhook history for the last 30 days, you can edit webhooks and add new ones.

Create a new webhook

Create a new webhooks via the API

This endpoint requires a Webhook object.

This endpoint returns a Webhook object.

POST /api/v1/webhooks/webhook

Update a Webhook

Updates an existing webhook via the API

This endpoint requires a Webhook object where the WebhookKey matches an existing webhook.

This endpoint returns a Webhook object.

PUT /api/v1/webhooks/webhook

View a Webhook

Returns an existing webhook via the API

This request URL requires a WebhookKey parameter that matches an existing webhook.

This endpoint returns a Webhook object.

GET /api/v1/webhooks/webhook/{WebhookKey}

View all Webhooks

Returns all existing webhooks via the API.

This endpoint returns an array of Webhook objects.

GET /api/v1/webhooks/webhook/list

Update a Webhook

Deletes an existing webhook via the API

This endpoint requires a WebhookKey that matches an existing webhook.

DELETE /api/v1/webhooks/webhook

View Webhook activity history

Returns details of all of the webhooks sent over the last 30 days.

This endpoint returns an array of WebhookHistory objects.

GET /api/v1/webhooks/webhook/history

Webhooks objects

Webhook

Field name Field type Mandatory on submission Description
webhookKey GUID No A unique reference to a webhook
events WebhookEvent array Yes The triggers for a webhook
authorisationToken String No A string that will be transformed to a SHA1 hash and sent with every webhook
callbackUri String (valid URL) Yes The endpoint to send the webhook to. Must be HTTPS.
{
  "webhookKey": "0DD8416A-BF8E-4598-BC3A-E1F1D4D65E0A",
  "events": [
    {
      "eventType": "OrderComplete",
      "eventSubscribed": true
    }
  ],
  "authorisationToken": "An authorisation key can be any text",
  "callbackUri": "https://api.verifile.co.uk/api/v1/webhooks/webhook"
}

Webhook event

Field name Field type Mandatory on submission Description
eventType Value Set Yes The type of event that triggers the webhook
eventSubscribed Bool Yes Whether or not the webhook is subscribed to the corresponding event type
{
  "eventType": "OrderComplete",
  "eventSubscribed": true
}

Webhook History

Field name Field type Description
orderId Int Reference to the Verifile order that triggered the webhook
eventType String The action that triggered the webhook
callbackUri String (URL) The endpoint the webhook was sent to
authorisationToken SHA1 Hash The hashed security token sent with the request
webhookSentDate DateTime The date the webhook was triggered
{
    "orderId": 591864,
    "eventType": "ApplicantFormSubmitted",
    "callbackUri": "https://api.verifile.co.uk/api/v1/webhooks/webhook",
    "authorisationToken": "a568707f5666ab86a4038c41e0cd33b14c48e7e3",
    "webhookSentDate": "2019-09-20"
}