This guide explains how to keep external systems – such as CRM systems, IPTV platforms, or mobile network components like the Home Subscriber Server (HSS) – in sync with PortaBilling. When changes occur in PortaBilling, e.g., an account is created, an invoice is issued, or a SIM card is activated, PortaBilling sends real-time updates to those systems. This process, known as provisioning, ensures that external systems receive up-to-date information needed to deliver services properly.
Provisioning relies on three key elements:
- Provisioning events – records of specific changes in PortaBilling (e.g., SIM card activation) that require synchronization with external systems.
- External System Provisioning Framework (ESPF) – the mechanism that detects provisioning events and sends them to external systems to update the data there.
- PortaBilling and ESPF APIs – used by external systems to retrieve detailed data and provisioning status.
Provisioning mechanisms
There are two primary ways the External System Provisioning Framework (ESPF) can integrate with external systems: event handlers and webhooks. Both serve the same purpose (keeping external systems in sync with PortaBilling events) but operate differently.
Event handlers
An event handler is a built-in or custom Perl module inside PortaBilling that reacts to specific events and directly communicates with a specific external system using this system's proprietary API. PortaBilling comes with a library of pre-developed event handlers for integrations it supports. You can order the development of custom event handlers from PortaOne.
Webhooks
A webhook is an automated notification that PortaBilling sends to an external application when a provisioning event occurs. This mechanism is implemented using a universal event handler called EventSender, which translates internal provisioning events into outgoing HTTP POST requests.
Webhooks offer a flexible alternative to built-in event handlers and are especially useful when a custom integration is needed. In this approach, you develop an external application that communicates with both PortaBilling and the external system. Instead of running the integration code internally, the ESPF sends an HTTP POST request to the application's URL whenever a relevant event occurs (e.g., when a SIM card is assigned to an account). The external application receives the event, retrieves the necessary data from PortaBilling via API, and then provisions the data to the external system.
Event handlers VS webhooks
| Aspect | Event Handler | Webhook (EventSender) |
|---|---|---|
| Implementation | Inside PortaBilling (built-in or custom Perl modules). | Outside PortaBilling (in your own external application, developed in any language or framework, hosted anywhere). |
| Use case | Integrations maintained by PortaOne (e.g., Yate HSS) | Integrations developed by 3rd parties |
| When a specific event occurs | PortaBilling calls an internal handler | PortaBilling sends an HTTP POST request (webhook) to a configured URL |
| Data access | Retrieves the necessary details via the PortaBilling API | |
| Error handling | PortaBilling tracks the status of each provisioning event (i.e., whether the provisioning succeeds or fails). If provisioning fails, the system automatically retries up to 10 times. Administrators can monitor the event’s status in the PortaBilling UI – including retry attempts and provisioning updates – and manually re-run the provisioning if needed (e.g., if automatic retries fail due to a temporary issue on the external system's side). | |
