API Reference

Getting Started with Bob Webhooks

Learn how to subscribe to events in Bob and be notified whenever a change occurs.

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

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 ↗.

Event types and their payload

Click the links below to learn about the available event types and thor payload:

Step 2: Validate your connection

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

If the server does not respond or returns an HTTP response other than '200' after a period of retries, Bob will inactivate the Webhook and email the admin instructing them to reactivate it from the Bob webhooks settings.

Once subscribed, an employee change event will be POSTed to the subscription URL.

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:

  1. Use the Webhooks' event payload as a notification only and then make an API call to retrieve all the necessary data. To learn more, see our best practices.
  2. The event listener should return a 200 status response for each event received so that Bob knows the event has been successfully processed. If you don't send the 200 response, the webhook will be deactivated in Bob, and you will need to re-activate it to continue your testing.
  3. Handle an 'incoming events' queue to buffer incoming events. To learn more, see our best practices.

👍

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.

Best practices

Follow these best practices when you develop your event listener Webhook to catch the events:

  1. Don't rely on the event's payload:
    When you implement the event listener on your side, consider that Bob Events sends some of the data related to the event as the event's payload. As a best practice, we advise using the Webhooks' event payload as a notification only and then making an API call to retrieve all the necessary data. To learn more, see Getting Started with the Bob API.
  2. Handle an 'incoming events' queue:
    Bob supports performing bulk changes that can be generated by either the client or a system update. If a bulk change is made, the server may receive multiple concurrent events indicating the changes that took place. To manage multiple concurrent events, we recommend creating a queue on the listener end. This queue will buffer incoming events, allowing the server to process them appropriately. This approach ensures that bulk changes are captured correctly and that your listener responds appropriately while maintaining the connection.

Manage Subscribed Webhooks in Bob

Once you subscribe, your subscribed Webhooks are listed on the Webhooks page Bob with the following details:

  • Name.
  • URL.
  • Secret.
  • Webhook status - active or inactive.
  • Created by.

To test webhooks, edit their details, activate or deactivate them, and view the webhook's log history, follow the step-by-step instructions in Manage Webhooks ↗.