Skip to content

Webhooks

Whenever an event occurs for a reference check you requested, Xref will submit a POST to your designated Webhook URL with information about the event. In order to receive webhooks, you will need to have a Webhook URL configured. The User-Agent for the requests will have the prefix Xref-Webhook/.

Responding to Webhooks

To acknowledge receipt of a webhook, your endpoint should return a 200 HTTP status code. Any other information returned in the response headers or response body is ignored. If a webhook is not successfully received for any reason, Xref will try to send it again in a few minutes. Webhook logs can be requested via the Logs endpoint.

Event Types

Below is a list of all possible events that can be sent by Xref. You can choose to subscribe to any combination of events that you want.

Event Description
employer.xref.request The employer has requested an Xref.
employer.xref.delete The employer has deleted an Xref.
employer.xref.stop The employer has stopped an Xref.
candidate.token.enter The candidate has accessed the Xref candidate app.
candidate.agree The candidate has agreed to the Xref collection statement.
candidate.verify The candidate has verified their details as provided by the employer.
candidate.decline.collection The candidate has declined the Xref collection statement.
candidate.submit The candidate has submitted referees.
referee.token.enter The referee has accessed the Xref referee app.
referee.token.start The referee has begun the Xref referee app process.
referee.agree The referee has agreed to the Xref collection statement.
referee.decline The referee has declined the Xref collection statement.
referee.verify.candidate The referee has verified their details as provided by the candidate.
referee.submit The referee has submitted their reference.
referee.save The referee has saved their reference and will finish it at a later time.
system.autodeclined The referee has not responded to the emails (or not accessed the Xref referee app) within 60 hours of the candidate submitting their details.
system.notified The system has sent an email reminder to the user specified in the payload.
system.notified.uar The system has notified that unusual activity status was updated.
system.xref.expired The system has notified an Xref Reference Survey has expired.

Sample Webhook Headers

Content-Type: application/json; charset=UTF-8
User-Agent: Xref-Webhook/1.0`
X-Xref-Signature: 376613f70d879d2ea719b11f34fd995c38c3a00a604480e7a81769b68e69374e

Sample Webhook Body

The event types generally follow the same schema, specified below:

{
"event": "employer.xref.request",
"webhook_url": "https://yourcompany.com/webhooks/xref/incoming",
"check": {
"id": 100,
"requested": "2017-11-10T06:40:08",
"state": "requested",
"state_last_updated": "2017-11-21T06:40:08",
"url": "/check/100",
"lifecycle_url": "https://report.xref.com/?t=bla",
"custom_id": "an optional unique string supplied by partner",
"integration": "app",
"integration_sub": "app_sub"
}
}

Some events will have additional data:

referee.*

All referee events additionally have a referee object, indicating which referee performed the specified action.

{
"event": "referee.submit",
"webhook_url": "https://yourcompany.com/webhooks/xref/incoming",
"check": {
"id": 100,
"requested": "2017-11-10T06:40:08",
"state": "requested",
"state_last_updated": "2017-11-21T06:40:08",
"url": "/check/100",
"lifecycle_url": "https://report.xref.com/?t=bla",
"custom_id": 100,
"integration": "app",
"integration_sub": "app_sub"
},
"referee": {
"id": 1,
"first_name": "Bla",
"last_name": "Bla",
"email": "bla@bla.com",
"state": "completed"
}
}

referee.submit will additionally have report_pdf_url inside referee object, a one-time clickable link to download that referee's PDF reference. It will also have a flag for unusual_activity. unusual_activity will be true if UA has been detected, else it will be false.

"referee": {
"id": 1,
"first_name": "Bla",
"last_name": "Bla",
"email": "bla@bla.com",
"state": "completed",
"report_pdf_url": "https://api-report.xref.com/xref-report?t=bla",
"unusual_activity": false
}

system.notified and system.autodeclined

The system.notified and system.autodeclined events have an additional user object, denoting which user was notified or autodeclined. The user_type field can be either referee or candidate.

{
"event": "system.notified",
"webhook_url": "https://yourcompany.com/webhooks/xref/incoming",
"check": {
"id": 100,
"requested": "2017-11-10T06:40:08",
"state": "requested",
"state_last_updated": "2017-11-21T06:40:08",
"url": "/check/100",
"lifecycle_url": "https://report.xref.com/?t=bla",
"custom_id": 100,
"integration": "app",
"integration_sub": "app_sub"
},
"user": {
"first_name": "Bla",
"last_name": "Bla",
"email": "bla@bla.com",
"user_type": "referee"
}
}

system.notified.uar

The system.notified.uar event informs the resolution of unusual activity. The user_type will be the employer who resolved the unusual activity. unusual_activity will either be confirmed if the user has marked the reference as suspicious, or an empty string ("") if it was marked as valid.

{
"event": "system.notified.uar",
"webhook_url": "https://yourcompany.com/webhooks/xref/incoming",
"check": {
"id": 100,
"requested": "2017-11-10T06:40:08",
"state": "completed",
"state_last_updated": "2017-11-21T06:40:08",
"url": "/check/100",
"lifecycle_url": "https://report.xref.com/?t=bla",
"custom_id": 100,
"integration": "app",
"integration_sub": "app_sub"
},
"user": {
"first_name": "Bla",
"last_name": "Bla",
"email": "bla@bla.com",
"user_type": "referee"
},
"referee": [{
"id": 100,
"first_name": "Bla",
"last_name": "Bla",
"email": "bla@bla.com",
"state": "answered",
"unusual_activity": "confirmed"
}]
}

system.xref.*

Events notifying Xref Reference Survey events additionally have a user object related to the employer.

{
"event": "employer.xref.request",
"webhook_url": "https://yourcompany.com/webhooks/xref/incoming",
"check": {
"id": 100,
"requested": "2017-11-10T06:40:08",
"state": "requested",
"state_last_updated": "2017-11-21T06:40:08",
"url": "/check/100",
"lifecycle_url": "https://report.xref.com/?t=bla",
"custom_id": "an optional unique string supplied by partner",
"integration": "app",
"integration_sub": "app_sub"
},
"user": {
"first_name": "Bla",
"last_name": "Bla",
"email": "bla@bla.com",
"user_type": "admin"
},
}

Securing Webhooks

For security reasons, you might want to verify that the requests you receive come from Xref. We pass along a hash signature with each request in the header X-Xref-Signature. When you receive a request, you can compute a hash and ensure that the one from Xref matches. The hash signature is generated with the HMAC algorithm, using your API key as a key and SHA256 digest mode.