Skip to main content

Webhook

1. Overview​

The Webhooks module in Sumo Ledger allows administrators to configure HTTP callback notifications that are triggered when specific events (called stages) occur within the system's processing pipelines. When a stage fires, Sumo Ledger sends an HTTP POST request to the configured URL, delivering event data to an external system in real time.

Webhooks are essential for integrating Sumo Ledger with third-party services, triggering downstream workflows, syncing data with external databases, or sending notifications when key ledger events occur.

Navigation: Configurations > General Settings > Webhooks

URL: https://las.ledger.raralabs.dev/settings/webhooks/list

2. Webhooks List View​

The list view displays all configured webhooks in a table with the following columns:

ColumnDescription
NameThe display name of the webhook.
URLThe endpoint URL that receives the HTTP POST callback.
StagesThe processing stage(s) that trigger this webhook.
Is EnabledWhether the webhook is currently active.

When no webhooks have been configured, the list displays "No results."

List View Actions​

  • + New Webhook: Opens the form to create a new webhook.

3. Creating a New Webhook​

Click "+ New Webhook" in the top-right corner. A modal dialog opens with the following fields:

3.1 Webhook Name (Required)​

A text field for the display name of the webhook. Choose a descriptive name that makes it clear what the webhook does (e.g., Loan Disbursement Notifier, Cheque Bounce Alert, Fee Processing Sync).

3.2 Stages (Multi-Select Dropdown)​

The Stages dropdown lets you select one or more processing stages that will trigger this webhook. Stages represent specific points in Sumo Ledger's processing pipelines where an event occurs. You can select multiple stages by checking the boxes next to each one.

The stages listed in the dropdown are dynamically generated based on the processes configured in your system. Each stage represents a specific step within a process pipeline, so the available options will differ depending on which processes have been set up under Configurations > General Settings > Process.

The All option at the top of the dropdown selects every available stage at once.

The naming convention follows the pattern process_name.stage_name, which tells you both the process pipeline and the specific step within it. For example, cheque_bounce.first_cheque_dishonor_entry refers to the first_cheque_dishonor_entry stage within the cheque_bounce process.

3.3 URL (Required)​

The endpoint URL that Sumo Ledger will send the HTTP POST request to when the selected stage(s) fire. This must be a fully qualified URL (e.g., https://api.example.com/webhooks/ledger).

Requirements:

  • Must be a valid HTTP or HTTPS URL.
  • The endpoint must be reachable from the Sumo Ledger server.
  • The endpoint should return a 2xx status code to acknowledge receipt; otherwise, the system will retry.

3.4 Description​

An optional text field for a human-readable description of the webhook's purpose. This is for administrative reference only and does not affect behavior.

3.5 Max Retry​

A numeric field that specifies how many times Sumo Ledger should retry the webhook call if the initial attempt fails. The default value is 3.

If the endpoint returns a non-2xx response or the connection times out, the system will retry up to this many times before marking the delivery as failed.

3.6 Enable​

A checkbox that determines whether the webhook is active. When unchecked, the webhook configuration is saved but no HTTP calls are made when the stage fires.

3.7 Saving​

Click "Add Webhook" to create the webhook.

4. Editing an Existing Webhook​

Click on any row in the Webhooks list to open the edit form. All fields are editable. After making changes, click the update button to save.

5. How Webhooks Work in Practice​

Event Flow​

  1. A transaction or process reaches a configured stage during execution.
  2. Sumo Ledger checks if any active webhooks are subscribed to that stage.
  3. For each matching webhook, the system sends an HTTP POST request to the configured URL with event data in the request body.
  4. If the endpoint responds with a 2xx status, delivery is considered successful.
  5. If the endpoint fails (non-2xx response or timeout), the system retries up to the Max Retry count.

Example Use Case​

Scenario: You want to notify an external fraud detection system every time a cheque bounce is recorded.

  1. Create a new webhook named Fraud Alert - Cheque Bounce.
  2. Select stages: cheque_bounce.first_cheque_dishonor_entry, cheque_bounce.update_dishonor_count.
  3. Set the URL to your fraud system's API endpoint: https://fraud.example.com/api/alerts.
  4. Set Max Retry to 5 for reliability.
  5. Check Enable.
  6. Click Add Webhook.

Now, every time a cheque dishonor event occurs, Sumo Ledger will POST the event data to your fraud system.

6. Best Practices​

  1. Use HTTPS endpoints. Always use HTTPS URLs to ensure webhook payloads are transmitted securely.
  2. Set appropriate retry counts. For critical integrations (e.g., payment notifications), increase the retry count. For non-critical ones (e.g., logging), the default of 3 is usually sufficient.
  3. Monitor webhook delivery. Check the Transaction Logs or system logs regularly to verify that webhooks are being delivered successfully.
  4. Keep webhook endpoints fast. The receiving endpoint should acknowledge the request quickly (return 200 OK) and process the payload asynchronously. Slow endpoints can cause timeouts and trigger unnecessary retries.
  5. Disable webhooks you're not using. If a webhook is no longer needed, uncheck the Enable box rather than deleting it. This preserves the configuration for future reference.
  6. Use descriptive names. A name like Daily Settlement Sync to ERP is far more useful than webhook1 when managing multiple webhooks.
  7. Select only the stages you need. Subscribing to too many stages can generate excessive traffic to your endpoint. Use the All option only when you truly need every event.