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.