HireHop can send a message with data to other apps when certain events are triggered within HireHop.  This message is called a webhook which automatically pushes the relevant data to the required location.

What is a webhook?

A webhook sends/pushes a message, with data attached to the message, when specific things happen in HireHop (an event).  Webhooks are sent via HTTP (calls a web address) and are a way of pushing data to other applications in real-time.  Webhooks deliver the relevant data to specific applications as it happens, meaning the receiving application gets data immediately after the event happens, which is far more efficient and faster than polling for data changes..

HireHop webhooks can be used to communicate directly with other apps or be sent to a connector like Zapier, that can be made to format the data and make any necessary API calls back to HireHop or to another application.

Setting up a webhook

In HireHop, go to “Settings” then click the “Company settings” tab and the “Webhooks” button at the top of the page.  In the popup window, click on the “New” button and add the URL where the webhook message is to be sent to and select every webhook that you want the URL to respond to.  You can add as many webhooks as you want, but should limit them to only the necessary ones that the specific URL will respond to.

A HireHop webhook will POST data to your URL endpoint as JSON, and will contain the following or similar data.

{
    "time": "2022-03-29 07:50:42",
    "user_id": 1,
    "user_name": "John Smith",
    "user_email": "john@email.com",
    "company_id": 1,
    "export_key": "22u43mrjwe7u",
    "event": "invoice.status.updated",
    "data": { ... },
    "changes": {
        "FIELD_NAME": {
            "from": "old",
            "to": "new"
        }, ...
    }
}

In the above JSON example, the following fields are:

• “time” is the UTC time and date the webhook was sent.
• “user_id” is the ID of the user who caused the event to be triggered.
• “user_name” is their user’s name.
• “company_id” field is the unique number identifier of the company the user works for.
• “export_key” is the value of the export key in company settings which can be used as a security check.
• “event” is the name of the webhook event that was triggered.
• “data” is the data that appertains to the webhook event.
• “changes” are the fields that changed, being what they were to what they got changed to.

HireHop will not wait for a response from the called URL or report an HTTP error from calling it.

Example PHP code for a URL endpoint to capture the webhook data would be:

<?php
	// Read the JSON data
	$postdata = file_get_contents('php://input');
	// Convert JSON data to an object
	$data_str = json_decode($postdata);
?>

HireHop is built on top of an API, meaning anything you see HireHop do, you can also accomplish using the extensive API.  All you need to access the Rest API is a user token applied as a GET or POST to the relevant URL endpoint.

API Tokens

To generate an API token, go to the “Settings” page and select the “Users” tab.  Select or create a user, then while that specific user is selected, click the “Menu” button then the “API token” option to generate a token.  The token will then display and can be copied to the clipboard using the copy button.

The token will become invalid if you change the email or password of the selected user, or you subsequently login to that user.  To prevent this from happening, you should create a dedicated API user, and for security give it the relevant permissions, thus restricting it from anything you will not be using the API for.

For security reasons, you should never use the token in front end JavaScript code, it should only be used server side, as if a hacker obtains the token, they can change and access your data on HireHop, so keep your token a secret.  If your token does get leaked, just change the password of the API user and generate a new token.

Using A Token

A token should be set as a GET or POST parameter that is called “token”.  For example, to load job data for job number 52, HireHop will call the API endpoint:

https://myhirehop.com/php_functions/job_refresh.php?job=52

If you want to call the same endpoint using a token, the URL would be:

https://myhirehop.com/php_functions/job_refresh.php?job=52&token=dqwejk5GVT65909bHHBN7922pq5hxjm%207hmn

Remember that when passing the token via GET (a URL parameter like above), you must encode the token first using a tool like https://meyerweb.com/eric/tools/dencoder.

Posting Data

To create or edit data in HireHop you must use a POST. When posting data, you should set only the fields that you want to change, for example to create or edit a job using the endpoint https://myhirehop.com/php_functions/job_save.php, setting the parameter “job” to “0” or omitting it will create a new job, anything else will edit the relevant job number.  So to edit the company name in job number 52, the post data should be:

{
"job" : 52,
"name" : "New Name",
"token" : "dqwejk5GVT65909bHHBN7922pq5hxjm=-7hmn"
}

API Endpoints

Many API endpoints are documented in the API documentation, with many more to follow.  To establish the endpoint for a task, in the HireHop application, use the browser network console to inspect the network calls and what parameters are set.  An extensive guide to the URL endpoints will be published soon.

Rate Limits

HireHop allows each user 60 connection requests within a 1 minute period.  If there are more than 60, a “Security warning, too many transactions” (327) error is returned.