Referoo API - Documentation

Webhook Documentation

Webhooks allow you to get notified when certain actions happen that are related to candidates created via the Referoo API. For example when a candidate has added all of their referee’s, or a referee has completed their reference.

How it works

A webhook call is an HTTPS request made by the Referoo server to a domain that you provide us with. Each requests body contains a JSON encoded object of the event thats happened and the details of the referee and candidate linked to that event.

Set-Up

Webhook events are available for candidates who are created via the API. To get started you’ll have to have implemented the Referoo API into your application and start creating candidates using it. Once this is done, you setup a webhook by doing the following:

Login to Referoo and go to Settings -> API Settings.
Click the Edit button on the Webhook URL item for the API client you want implement webhooks into.
Add the Webhook URL and click save.

Note: The URL must accept POST requests

To make your webhook URL as secure as possible it’s recommended that you do the following as the bare minimum:

Ensure that the webhook URL isn’t indexed.
Ensure that it’s not guessable.
Check the signature of the webhook (see Authentication section below).

Authentication

It is also recommend that you check the signature that is returned by the webhook. Below is the process for doing that.

First, log in to Referoo and find your Webhook Signing Secret. Navigate to the settings menu at the top of the page, then find the API settings in the left hand menu. On the API Settings page, find the Webhook signing secret for your API Client.

An example of a signing secret in Referoo

There is a Referoo-Signature header included in each signed event contains a timestamp as well as the signature. Each value is comma seperated. The timestamp is prefixed by t=, and the signature is prefixed with s=. Here is an example:

Referoo-Signature: t=1621468469,s=f69d40049dae3509495a51c3be85e222fa4ef43e39932659cdc5156b2da6ab26

To find out if a signature is valid. Create a string that contains the timestamp sent, then the character ., followed by the contents of the request body (the raw request payload, which should be in JSON format):

{{time_stamp}}.{{request_payload}}

Then, compute an HMAC with SHA256, use the string created in the previous paragraph as the message and use your signing secret as the key. You should find that the computed value matches the value sent in the header.

Note: You must use the data from the raw request body for the request_payload. If you've converted the request body to an array or object, then converted it back to a JSON string, its likely to be a slightly different format and validation will fail. If you're having having trouble validating the signature and are using a function such as json_encode, or JSON.stringify, then you might not be using the raw request data.

Supported Events

A webhook request can be made when the following events happen:

Event	Description
`candidate_added_a_referee`	Fires when a candidate has added a reference or a reference was added via the candidate detail page by a recruiter.
`candidate_added_all_of_their_referees`	This fires after a candidate has added all of their references via the candidate dash or the phone questionnaire.
`referee_completed_a_reference`	Fires when referee completes their reference via the referee dash, or when a recruiter completes it via the phone questionnaire.
`reference_has_been_updated`	Fires when a referee has updated their reference or a recruiter has updated on the referee's behalf.
`referee_has_been_updated`	Fires when a referee has been updated by the candidate or the referee themselves. Note: Does not fire when a recruiter updates a referee via the candidate detail page.
`referee_dash_email_bounced`	Fires when we attempt to send the referee a reference request email, but it bounces because the email address was incorrect.
`candidate_dash_email_bounced`	Fires when we attempt to send the candidate a referee request email, but it bounces as the email address was incorrect.
`referee_cancelled_reference`	Fires when a referee declines to leave a reference. This is sent if a referee is sent a referee dash email and declines to leave a reference.
`referee_candidate_matching_ip`	Fires when a referee and candidate have the same IP Address or the same browser unique ID. This is sent after a referee completes their reference via the referee dash. A detailed description of the reason the warning was thrown will be returned in a `warnings` item thats at the top level of the JSON object.

When you provide us with your Webhook URL you’ll need to let us know which events you’d like to receive requests for.

Data Format

All webhook requests are made using POST. The Webhook request body will contain data in the following format:

    {
        "candidate": {
            "num":"12345",
            "unique_id":"123456abcd",
            "first_name":"John",
            "last_name":"Smith",
            "email":"john@example.com",
            "Phone":"1234567890",
            "job":"Candidates job",
            "ip_address":"1.1.1.1",
            "number_of_references_required": "2",
            "number_of_references_completed": "2",
            "custom_data": "Sample candidate custom data",
        },
        "referee":{
            "num":"12345",
            "unique_id": "123456abcd",
            "name":"Tom Jones",
            "email":"tom@example.com",
            "phone":"1234567890",
            "relationship":"I managed the candidate",
            "Job_title":"Manager",
            "candidate_job_title":"Jnr Programmer",
            "company":"Example LTD",
            "start":"January 2013",
            "declined": "1",
            "reason_for_declining": "The referee's reason for declining will appear here (if applicable)",
            "reference_completed": "1",
            "ip_address": "1.1.1.1",
            "custom_data": "Sample referee custom data",
        },
        "event":"referee_has_been_updated",
        "call_id":123
    }

The webhook request will always contain the data in the format above. For the event, Candidate added all of their referees the referee JSON object will be empty.

Webhook Call Logging and Error reporting

Logging

At the bottom of the settings page for your API Client you can see a list of Recent webhook calls and their statuses. You can also replay a failed webhook call manually to help debug issues that you have with processing requests.

Error Reporting

We have a system that allows an email to be sent to you each time a webhook call doesn't return a HTTP status code of 200. Click the edit button next to the Webhook Settings to enable this feature for your API client.