A webhook is an automated method of communication between two applications. It enables real-time data delivery from one application to another by triggering an HTTP POST request to a specified URL. Webhooks are commonly used for instant notifications and data synchronization between different systems.
The HRMS application leverages webhooks to notify external systems, about employee-related events such as creation, updates, or deactivation. The HRMS application sends these notifications to a designated webhook URL provided.
Supported events
Employee events are categorised into the following types, each sent alongside the payload:
{
"event": "create_employee",
"data": {
"title": "Mr",
"first_name": "Demouuu",
"last_name": "Account",
"other_names": "ANother",
"email": "[email protected]",
"phone": "07057646553",
"employee_code": "SHR-DOT82833",
"gender": "Male",
"age": 40,
"date_of_birth": "1984-03-07T23:00:00.000000Z",
"marital_status": "Single",
"employment_date": "2024-02-29T23:00:00.000000Z",
"job_role": "Admin associate",
"department": null,
"paygroup": "Junior Level",
"paygrade": "Junior Associate I",
"line_manager": "********* *********",
"cost_center": "All",
"branch": "Ajah",
"region": "All",
"unit": "Admin",
"state_of_origin": null,
"residential_address": null,
"permanent_address": null,
"exit_date": null,
"confirmation_status": "Unconfirmed",
"contract_type": "Full time",
"contract_start_date": "2024-03-01",
"entity": "Seamless-Tech"
}
}
{
"event": "update_employee",
"data": {
"title": "Mr",
"first_name": "Demouuu",
"last_name": "Account",
"other_names": "ANother",
"email": "[email protected]",
"phone": "07057646553",
"employee_code": "SHR-DOT82833",
"gender": "Male",
"age": 40,
"date_of_birth": "1984-03-07T23:00:00.000000Z",
"marital_status": "Single",
"employment_date": "2024-02-29T23:00:00.000000Z",
"job_role": "Admin associate",
"department": null,
"paygroup": "Junior Level",
"paygrade": "Junior Associate I",
"line_manager": "********* *********",
"cost_center": "All",
"branch": "Ajah",
"region": "All",
"unit": "Admin",
"state_of_origin": null,
"residential_address": null,
"permanent_address": null,
"exit_date": null,
"confirmation_status": "Unconfirmed",
"contract_type": "Full time",
"contract_start_date": "2024-03-01",
"entity": "Seamless-Tech"
}
}
{
"event": "deactivate_employee",
"data": {
"title": "Mr",
"first_name": "Demouuu",
"last_name": "Account",
"other_names": "ANother",
"email": "[email protected]",
"phone": "07057646553",
"employee_code": "SHR-DOT82833",
"gender": "Male",
"age": 40,
"date_of_birth": "1984-03-07T23:00:00.000000Z",
"marital_status": "Single",
"employment_date": "2024-02-29T23:00:00.000000Z",
"job_role": "Admin associate",
"department": null,
"paygroup": "Junior Level",
"paygrade": "Junior Associate I",
"line_manager": "********* *********",
"cost_center": "All",
"branch": "Ajah",
"region": "All",
"unit": "Admin",
"state_of_origin": null,
"residential_address": null,
"permanent_address": null,
"exit_date": "2024-01-30",
"confirmation_status": "Unconfirmed",
"contract_type": "Full time",
"contract_start_date": "2024-03-01",
"entity": "Seamless-Tech"
}
}
Webhook Signature Validation
SeamlessHR events include the "x-seamlesshr-signature" header. The value of this header is an HMAC SHA512 signature of the event payload signed using your secret key. It is required to verify the header signature before processing the event:
const crypto = require('crypto');
const secret = process.env.SECRET_KEY;
// Using Express
app.post("/webhook/url", function(req, res) {
// verify signature
const hash = crypto.createHmac('sha512', secret).update(JSON.stringify(req.body)).digest('hex');
if (hash == req.headers['x-seamlesshr-signature']) {
// Retrieve the request's body
const event = req.body;
// Do something with event
}
res.send(200);
});
<?php
// only a post with paystack signature header gets our attention
if ((strtoupper($_SERVER['REQUEST_METHOD']) != 'POST' ) || !array_key_exists('HTTP_X_SEAMLESSHR_SIGNATURE', $_SERVER) )
exit();
// Retrieve the request's body
$input = @file_get_contents("php://input");
define('SEAMLESSHR_SECRET_KEY','SECRET_KEY');
// verify signature
if($_SERVER['HTTP_X_SEAMLESSHR_SIGNATURE'] !== hash_hmac('sha512', $input, SEAMLESSHR_SECRET_KEY))
exit();
http_response_code(200);
// parse event (which is json string) as object
// Do something - that will not take long - with $event
$event = json_decode($input);
exit();
?>