Overview

Webhooks allow your application to receive real-time notifications when certain events occur on specific resources in our system. When an event occurs on a subscribed channel, a POST request is sent to the URL you provide with detailed information about the event.

You can subscribe to different channels. Channels allow you to listen for specific events such as created, updated and deleted actions.

Available Channels and Events

Below is a list of available channels and the events you can subscribe to for each:

Name	Channel	Events
Business	business	updated
Invoices	invoices	created, updated, deleted
Invoice Payments	invoice_payments	created, updated, deleted
Invoice Online Payments	invoice_online_payments	created
Sales	sales	created, updated, deleted
Deposits	deposits	created, updated, deleted
Quotes	quotes	created, updated, deleted
Other Incomes	other_incomes	created, updated, deleted
Clients	clients	created, updated, deleted
Expenses	expenses	created, updated, deleted
Bills	bills	created, updated, deleted
Bill Payments	bill_payments	created, updated, deleted
Bill Online Payments	bill_online_payments	created
Income Tax Payments	income_tax_payments	created, deleted
Withholding Tax Payments	withholding_tax_payments	created, deleted
Sales Tax Payments	sales_tax_payments	created, deleted
Suppliers	suppliers	created, updated, deleted
Employees	employees	created, updated, deleted
Pay Runs	pay_runs	created, updated, deleted
Pay Run Salary Payment	salary_payments	created, deleted
Pay Run Tier 1 Payment	payrun_tier1_payments	created, deleted
Pay Run Tier 2 Payment	payrun_tier2_payments	created, deleted
Pay Run Tier 3 Payment	payrun_tier3_payments	created, deleted
Pay Run Income Tax Payment	payrun_income_tax_payments	created, deleted
Products / Services	products_services	created, updated, deleted
Wallet Transactions	wallet_transactions	created
Bank Transfers	bank_transfers	created, updated, deleted
Accounts	accounts	created, updated, deleted
Journals	journals	created, updated, deleted
Business Loans	business_loans	created, updated, deleted
Ledgers	ledgers	created, updated, deleted

Webhook Data Structure

Each time an event occurs on a subscribed channel, we send a POST request to your webhook URL with the following structure:

content_copyjson
{
  "event": "channel.event",
  "message": "Channel event successful.",
  "idempotency_key": "26053e97-f78a-4d25-a519-4eed22ba5c41",
  "environment": "staging",
  "data": {
    "id": 1,
    "tag": "adasd"
    // Additional model-specific fields can be added here
  }
}

• event: The channel and event that triggered the webhook, formatted as channel.event (e.g., business_loans.deleted, invoices.created).
• message: A description of the event that occurred (e.g., “Business Loan deleted successfully”).
• idempotency_key: A unique key for each request. This helps your system ensure that the same webhook is not processed multiple times.
• environment: The environment from which the webhook was sent, either staging or production.
• data: The event-specific data. This may vary depending on the channel and event.

Example Webhook Data

For the business_loans.deleted event, the data structure would look like this:

content_copyjson
{
  "event": "business_loans.deleted",
  "message": "Business_Loan deleted successfully.",
  "idempotency_key": "26053e97-f78a-4d25-a519-4eed22ba5c41",
  "environment": "staging",
  "data": {
    "id": 1,
    "tag": "adasd"
    // Additional model-specific fields are added here
  }
}

In this example:

• The event is business_loans.deleted, indicating that the event pertains to a Business Loan resource being deleted.
• The message provides a brief description of the event, such as “Business_Loan deleted successfully.”
• The idempotency_key is unique to this webhook request and can be used to prevent duplicate processing of the same event.
• The environment is staging, meaning the webhook was sent from the staging environment.
• The data section contains the details of the event, such as the id of the affected business loan and its tag.

Steps to Create a Webhook

1. Go to the Developer Console:

Log in to your developer account and go to the Developer Console where you can manage your webhooks.

2. Create a Webhook with URL and Channels:

In the Developer Console, Click on the Webhook tab. Here you can create or update your webhook. You can also see how your webhook is performing as well send a test request to ensure it is able to receive requests from our systems.

Note: It’s recommended to test webhooks in the sandbox environment before going live in production.

Security Considerations

• Verify Webhook Integrity:

We recommend verifying the integrity of each webhook request to ensure it comes from our system. One method is to use the idempotency_key to check if the event has already been processed.

• Use Secure Endpoints:

Ensure your webhook URL uses HTTPS to protect sensitive data in transit.