​
Create Webhooks

To create webhooks follow the intructions up ahead!

Step 1: Navigate to the “Webhooks” section from the sidebar under the “Configure” menu.

Step 2: In the “New webhook” section, enter the destination URL where you want to receive the webhook notifications in the “Destination URL” field.

Step 3: Optionally, click the “Test URL” button to ensure that your destination URL is correctly set up and can receive test data.

Step 4: Provide a meaningful name for your webhook in the “Webhook Name” field. For example, “Employee data.”

Step 5: Choose the events for which you want to receive notifications by selecting the appropriate checkboxes:

  • Sync start: Receive an alert when a connector’s sync starts.
  • Sync error: Get notified when a connector sync fails.
  • Sync completed: Get notified when a connector sync job is successful.
  • Employee model change: Receive an alert when any employee data is modified.
  • Data model change: Receive an alert when any data model is modified.

Step 6: Once you have filled in all the required fields and selected the notification triggers, click the “Create webhook” button to save your webhook configuration.

​
Payload Properties

  • hook: The webhook that was triggered.
  • connector: The connector whose data has changed.
  • data: The affected data model.

​
Webhook event types

  • Connector Sync Started
  • Connector Synced
  • Connector Sync Error
  • Employee Data Changed
  • Connector Data Modified

​
Sample payload for webhook events

Recieve an alert when the connector sync starts

{
    "webhook": {
        "webhook_id": "10c9a6b1-4ea8-476e-bdb0-193001a94a8d",
        "url": "https://webhook-test.com/8e771727c78e3a4017f374fb745313b6",
        "event": "connector_sync_started"
    },
    "connector": {
        "id": "018f99e2-ed3a-7f4c-ae97-83d619bdf95c",
        "display_name": "BreatheHR",
        "categories": [
        "HRIS"
        ],
        "org_name": "Test Org",
        "connector_status": "COMPLETE",
        "end_user_name": "John Doe",
        "end_user_email": "abc@xyz.com"
    },
    "data": {
        "id": "018f99e7-886b-7c9f-a63a-f6fbc9da1f83",
        "integration_name": "breathehr",
        "initial_sync": true,
        "category": "HRIS",
        "display_status": "Syncing",
        "last_sync_start_time": "2024-07-22T09:49:30.478384+00:00"
    }
}

​
Security

To secure your API endpoint, ensure it verifies that POST requests are genuinely from Bindbee and not from a malicious source, and that payloads haven’t been tampered with during transit.

You can achieve this by checking if the X-Bindbee-Webhook-Signature field in the request header matches an encoded combination of your organization’s unique webhook signature and the payload of the incoming request.

In the Webhooks configuration page, you should find a Security section where you can access your signature key. This key is unique to your organization and can be regenerated if it becomes known to an unauthorized party.

import base64
import hashlib
import hmac
 
# Replace 'YOUR_WEBHOOK_SIGNATURE_KEY' with the actual key from:
# https://app.bindbee.dev/webhooks
 
signature_key = "YOUR_WEBHOOK_SIGNATURE_KEY"
request_body = request.body
 
# Ensure the presence of a signature header in the request
if "X-Bindbee-Webhook-Signature" not in request.headers:
    print('Signature header missing; request may not be from Bindbee.')
    raise
 
# Retrieve the signature header from the request
received_signature = request.headers["X-Bindbee-Webhook-Signature"]
 
# Convert the key and request body to bytes
key_bytes = signature_key.encode("utf-8")
body_bytes = request_body.encode("utf-8")
 
# Create an HMAC digest using SHA-256
hmac_digest = hmac.new(key_bytes, body_bytes, hashlib.sha256).digest()
 
# Encode the digest to base64
encoded_digest = base64.urlsafe_b64encode(hmac_digest).decode()
 
# Use `hmac.compare_digest` to compare the computed digest with the received signature
signature_valid = hmac.compare_digest(encoded_digest, received_signature)

​
Webhook Visibility

The webhook logs are easily visible on the webhooks tab at Bindbee dashboard. The specific webhook logs will be visible on the individual webhook page.