Bob provides the ability to subscribe to events that occur in the system. You should provide a Webhook URL, which will be called whenever an event occurs. Each event will send the information about the event in the event's payload.

To start working with Webhooks:

• Step 1:  Subscribe to events
• Step 2: Validate your connection
• Step 3: Authenticate your events
• Step 4: Develop the event lisener
• Step 5: Test your webhooks

Step 1: Subscribe to events

To get started, you should subscribe to events in Bob and provide the Webhook URL pointing to your listener.

For step-by-step instructions, see How to subscribe to Webhook events ↗.

Step 2: Validate your connection

Bob uses a validation mechanism that checks the availability of the Webhook listener:

1. Bob server sends a test event to the webhook listener server when establishing a new webhook connection.
2. The test event is sent as a POST request:
   • "Ping test" as a String
   • If previous failed we send a JSON: {"text":"Ping test"}
3. Your listener endpoint should listen to this POST event, and return immediately a successful status code (2xx).
4. Once the connection is established, Bob sends the the relevant events as POST requests to the listener URL.

📘

Notes:

1. If your listener does not respond or returns an HTTP response other than '200' after a period of retries, connection will not be established.
2. To increase security while using webhooks, you can whitelist Bob's IPs ↗.

Step 3: Authenticate your events

Requests from Bob to your system will be signed, and the secret signature can be grabbed from the Bob UI as part of the Webhook configuration.

The algorithm used for creating the signature is HMAC SHA512. As shown in the example below, the signature is created by employing HMAC SHA512 on the request payload and the secret token given. The signature itself is sent as the header attribute - Bob-Signature.

Here is an example of how you can calculate the signature.

import java.nio.charset.StandardCharsets._
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

import org.apache.commons.codec.binary.Base64

private def getSignature(secret: String, content: Array[Byte]) = {
    val mac = Mac.getInstance("HmacSHA512")
    val key = new SecretKeySpec(secret.getBytes(UTF_8), "HmacSHA512")
    mac.init(key)
    val signature = mac.doFinal(content)
    Base64.encodeBase64String(signature)
  }

digest = OpenSSL::Digest.new('sha512')
Base64.encode64(OpenSSL::HMAC.digest(digest, secret_key, body))

<?php
  // Requires PHP >= 5.1.2 and PECL hash >= 1.1
  $signature = base64_encode(hash_hmac('sha512', $body, $secret_key, true));
?>

$token = "THE_TOKEN_THAT_WAS_PROVIDED"
    $payload = "THE PAYLOAD"
    $encodedToken = [Text.Encoding]::UTF8.GetBytes($token)
    $hmacsha = New-Object System.Security.Cryptography.HMACSHA512 (,$encodedToken)
    $signature = $hmacsha.ComputeHash([Text.Encoding]::UTF8.GetBytes($payload))
    $signature = [Convert]::ToBase64String($signature)

import crypto from 'crypto';
var hmac = crypto.createHmac("sha512", secret);
var signature = hmac.update(new Buffer(json, 'utf-8')).digest("base64");

Step 4: Develop your event listener

In this step, you should develop the webhook listener to catch the events Bob sends to your URL.

Follow these best practices to endure seamless implementation.

Step 5: Test you webhooks

You can use webhook testing tools to listen to the events and review the payload before you start coding the listener or code the listener and test the workflow in your environment.

👍

Testing Webhooks

For testing, consider using event listeners. These are online services that allow users to create and manage custom webhook endpoints for testing webhooks. This will enable you to see the events Bob sends when you subscribe, even before you develop your own event listener.
Disclaimer: Sending events to an external tool means you may expose your data. Make sure you trust the tool with your data.

Before you begin

• Ensure you’ve set up a webhook in Bob and have a working listener endpoint.
• Ensure you validate your connection.
• Ensure you have access to your Bob admin account to perform actions like updating employee details or time-off requests.

Step 1: Simulate events for testing

In this example, we will simulate the time off created event.

To trigger the Event in Bob, follow the steps in Manage time off requests to create a new time off request for an employee.

Step 2: Verify the event payload

Check your webhook listener to confirm it received the timeoff.request.requested event with the relevant employee ID.

Example payload:

{
  "timeoffRequestId": 24588163,
  "employeeId": "3332883916968166175",
  "event": "timeoff.request.requested",
  "getApi": "https://api.hibob.com/v1/timeoff/employees/3332883916968166175/requests/24588163"
}

Step 3: Fetch details about the request

Use Bob’s API to fetch full details about the time off request.
For some events Bob provides the getApi property in the payload, which already includes the URL to the relevant endpoints, with ready-made query parameters containing the relevant employee ID and request ID:

GET  https://api.hibob.com/v1/timeoff/employees/3332883916968166175/requests/24588163  

Next Steps

Once you’ve tested the events, you can use them to:

• Update external systems (e.g., sync employee changes with your CRM).
• Automate workflows based on system updates to employee, time off requests, or other entities.