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": "samlpeuser@gmail.com", 
        "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": "samlpeuser@gmail.com", 
        "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": "samlpeuser@gmail.com", 
        "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();
?>