benbase logo

Webhooks

Benbase uses Svix to send webhooks for various events. This page explains how to set up and manage webhooks through the Svix portal.

Overview

Webhooks are HTTP callbacks that notify your system when events occur in Benbase. They allow you to stay synchronized with real-time updates without polling the API.

Getting Started

1. Access the Svix Portal

To access the Svix portal for webhook management:

  1. Login to Benbase Embed: Visit the appropriate environment:

  2. Navigate to Svix Portal: Once logged in with your account, go to the Svix Portal Access tab

  3. Generate Portal URL: Click on Get Portal URL to generate a unique URL for accessing the Svix portal

  4. Access Portal: Use the generated URL to access your Svix portal where you can configure webhook endpoints and view event logs

To revoke all active portal sessions, click on the Revoke All Sessions button in the Svix Portal Access tab

2. Configure Your Webhook Endpoint

In the Svix portal, you can:

  • Set up webhook endpoints - Configure the URL where webhooks should be sent
  • Customize payloads - Modify the webhook data structure to match your system requirements
  • Set up filtering - Choose which events to receive
  • View event logs - Monitor webhook delivery and retry attempts
  • Test webhooks - Send custom payloads to test your integration

3. Handle Webhook Events

When webhooks are received, your system should:

  1. Verify the signature - Ensure the webhook is coming from Benbase
  2. Process the event - Handle the event data according to your business logic
  3. Return a 2xx response - Confirm successful processing within 15 seconds

Webhook Processing

Response Requirements

Webhooks must return a 2xx status code within 15 seconds to be considered successfully processed

Disable CSRF protection for your webhook endpoints if your framework enables it by default

Security

Always verify webhook signatures and timestamps when processing webhook events

The Svix portal provides built-in signature verification tools and libraries for various programming languages. Learn more about webhook verification here.

Testing

For comprehensive guidance on testing webhooks, including how to send test payloads, debug delivery issues, and monitor webhook performance, see the Svix Webhook Testing Guide.

Available Events

Benbase sends the following webhook events:

Deduction Changes

  • Deprecated employee.deduction-created - Triggered when a new deduction is created for an employee (this event will be deprecated in the future, please use updated event instead)
  • employee.deduction-updated - Triggered when an existing deduction is modified

Employee Census

  • employee-census.sync-request - Triggered when Benbase requires employee census data
  • employee-census.sync-complete - Triggered when Benbase employee census sync is complete

Each event type has its own payload structure. See the specific documentation pages for detailed payload examples.

Additional Resources

For more information about webhook consumption and using the Svix portal, visit the Svix webhook documentation.

The Svix portal provides comprehensive tools for webhook management, including debugging, testing, and monitoring capabilities

Was this page helpful?