Provisioning via webhooks

Link copied to clipboard

This is an alternative approach to data provisioning. Webhooks allow your external application to receive notifications about provisioning events happening in PortaBilling.

Provisioning via webhooks

For simplicity, provisioning events are grouped into four category types:

  • Customer – the event types of this group notify that a customer record has been created, updated, or deleted in PortaBilling.

  • Subscriber – the event types of this group notify that an account record has been created, updated, or deleted in PortaBilling.

  • DID – the event types of this group notify that a DID number has been added, updated (assigned to / unassigned from a customer or account), or deleted in PortaBilling.

  • Invoice – the event types of this group notify that an invoice has been created or updated (paid fully or partially, or refunded) in PortaBilling.

An external application subscribes to receive these event types. Once an event occurs, the ESPF maps it to the corresponding event type and sends the HTTP POST request to the application’s URL. The request body contains the event type and the ID of the provisioned entity in JSON format.

For example, when a new SIM card is assigned to a subscriber in PortaBilling, the ESPF sends an HTTP POST request as follows:

http://127.X.X.X:5000:
{
"event_type": "Subscriber/Updated",
"variables": {
"i_event": "5"
"i_account": "1000889"
}
}

Your application receives the request, queries the information related to this event type (SIM card details such as IMSI, MSISDN) from PortaBilling via the API, and triggers the API call in the HSS to activate the SIM card.

The i_event variable in the request enables the application to determine whether it is a new request or a retry. The application must be able to store requests, identify them by the i_event variable and check for retries.

In the case of a retry, the application verifies the request’s status. If the request was already processed, the application responds with 200OK. Otherwise, the application treats it as a new request and processes it accordingly.

To illustrate the flow in detail, consider the following example:

An administrator creates a new account record in PortaBilling. The ESPF sends the HTTP POST request with the Subscriber/Created event type and i_event:5 to the external application. The application retrieves the account service configuration from PortaBilling and provisions the external system. If the ESPF receives no response from the application during the timeout (e.g., 30 seconds), it resends the request.

The application determines that it is the same request (i_event:5) and searches its own event queue. If provisioning is successful but takes longer, the application does not attempt to provision that subscriber again. Otherwise, it re-provisions the external system.

When the ESPF sends several events that relate to the same entity (e.g., have the same i_account value), the application uses the i_event values to sort them in the correct order.

Tips Note that using the ESPF API, you can add events to the queue and schedule the time when they must be processed. Refer to the Provisioning Application Reference guide to see the configuration details and the example of the usage scenario.

Components

Link copied to clipboard

Your external application operates as the middleware between PortaBilling and the external system it provisions. You can develop it in any programming language (e.g., Java, Python, etc.) and host it on a remote web server or in a cloud.

To provide an additional layer of security to communications between your external system and PortaBilling, you can use a cryptographic signature for HTTP requests.

The ESPF sends HTTP POST requests using the EventSender handler. It supports all provisioning events and operates in asynchronous mode by default. To prevent system overload in case of large numbers of events, the EventSender controls the number of parallel requests. And, if necessary, you can always change the handler to operate in synchronous mode.

The ESPF can send HTTP POST requests to more than one external application. This enables you to provision data to several external systems at the same time.

For example, you integrate PortaBilling with the HSS and the IPTV platform to provide both mobile and IPTV services. When you register a new account in PortaBilling, the ESPF sends a provisioning request to both the HSS and the IPTV platforms.

If a user’s service configuration includes only one service (e.g., IPTV), this request is useless for the HSS. Therefore, if a service is not used by a subscriber, make sure that the application to provision the HSS ignores it.

You can configure the ESPF to differentiate among provisioning data and send specific event types to each system. To make this happen, please contact PortaOne support. This configuration requires deep knowledge of ESPF architecture.

Provisioning event version

Link copied to clipboard

The EventSender handler supports both simplified and standard provisioning events. We recommend that you develop the external application to operate with the simplified events. If the simplified events do not meet the system’s requirements for provisioning, you develop a web application to process the standard provisioning events.

Depending on an application’s logic, you can now configure the ESPF to send a desired version of the provisioning events on the Configuration server. Simply select the value for the EventSender.APIVersion option, where:

  • 1 stands for standard provisioning events, and

  • 2 – for simplified provisioning events.

Provisioning event version

The external systems you provision may require different event versions. For example, the HSS requires standard events while the CRM system you integrate with PortaBilling can be provisioned using the simplified events. In this case, fine-tune the ESPF to send the correct version to either application:

  1. Configure the default event version for the ESPF as described above. All applications operate with it when you add more external systems to your infrastructure.

  2. Define the event version for a particular web application. Enter the following string in the ESPF.CustomIniOptions option on the Configuration server:

    [EventSender]APIVersionForReceivers=https://mycompany.com=version,

    where:

    • https://mycompany.com is the URL of the web application, and

    • version is the provisioning event version value.

Configuration

Link copied to clipboard

Please refer to the Provisioning Application Reference Guide for guidelines on how to develop an external application to provision data from PortaSwitch.

Supported event handlers

Built-in integrations

Link copied to clipboard

PortaBilling is supplied with these handlers to provision data to external systems:

  • AricentHSS – this handler provisions subscriber information such as the user’s phone number and SIM card details to the Aricent HSS and Adax HSS. It also provisions subscriber’s service configuration (static IP address, quality of service information).

  • AudioCodes – this handler provisions subscriber information such as the user’s phone number, SIM card details, status, registration (SIP parameters), mobile device (IMEI, language, etc.) and custom configurations to the AudioCodes CMMS (Clients’ Management Server).

  • Calix – this handler provisions ONT device information such as FSAN serial number plus account and service configuration data (e.g., account status, bandwidth profile ID within the Internet service policy) to the Calix Management System, the platform that controls Internet service availability for subscribers in fiber-optic networks such as GPON/Active Ethernet.
  • CLDB – this handler provisions subscriber information (account ID, MAC address), billing status and service configuration data (e.g., product, speed limit changes) to the external database CLDB.

  • ECConnect – this handler provisions subscriber information such as service configuration (allowed services), billing status and SIM card details (MSISDN, ICCID) to the ECConnect Access Portal (EAP) platform. EAP acts as the middleware between PortaBilling and the Optus mobile core to activate mobile services for subscribers.

  • EventSender – this is a universal handler to provision any external system. Since it sends HTTP POST requests with provisioning events to an external application, it’s the middleware between PortaSwitch and an external system. The application can be written in any programming language. It must be able to process provisioning events and communicate with PortaSwitch and the external system via their API.

  • Huawei::HSS – this handler provisions subscriber information such as the user’s phone number and SIM card details to the Huawei HSS.

  • Huawei::PCRF – this handler provisions the subscriber’s service configuration (service and policy name, QoS parameters) to Huawei PCRF.

  • IPTV – this handler provisions available channel information to one of the PortaSwitch supported IPTV platforms (i.e. MatrixStream, Minerva, Telebreeze IPTV) when either new or existing customers sign up for the IPTV service.

  • Jasper – this handler provisions subscriber and SIM card information to the Cisco Jasper connectivity management platform.

  • NetNumber – this handler provisions ported-in numbers to the NetNumber SMS/MMS database.
  • ReadyWireless – this handler provisions the subscriber’s phone number and device (IMEI) to ReadyWireless MVNE to trigger device activation/deactivation.

  • Sandvine – this handler provisions subscriber details such as username, static IP address/netmask, service provider identifier, and Internet access policy details to Sandvine SPB (Subscriber Policy Broker). Sandvine SPB is a component of the Sandvine DPI (Deep Packet Inspection) solution. It enables you to shape network traffic and introduce policy enforcement on a per-subscriber basis.

  • Titan::HSS – this handler provisions subscriber information such as the user’s phone number and SIM card details to NetNumber Titan HSS. It also provisions subscriber’s service configuration – Regular upload/download limits for Internet access, APN (Access Point Name) ID, Roaming profile ID.

  • YateHSS – this handler provisions subscriber information such as the user’s phone number, their SIM card details, and user’s status to Yate HSS/HLR.

  • ZXUN::HSS – this handler provisions subscriber information such as the user’s phone number, SIM card details, and their account status to the ZTE HSS.

  • ZXUN::SPR – this handler provisions the subscriber’s service configuration, user’s phone number, and SIM card details to the ZTE SPR.

Internal handlers

Link copied to clipboard

Changes in customer, product, and service configuration influence the configuration of accounts in PortaBilling. For example, when a customer reaches their credit limit, services are no longer available to their credit accounts until the customer’s balance is refilled.

To reduce the load on the system in such cases, ESPF is supplied with handlers that process product, customer, and service configuration events, and then create events for accounts and place them in the event queue:

  • CustomerToAccountsDispatcher – this handler processes customer status changes and provisions them to all customer accounts.

  • ProductToAccountsDispatcher – this handler processes all changes at the product level and provisions them to an account that has this product assigned to it.

  • ServiceAttributeDispatcher – this handler provisions changes in service configuration to both customers and accounts.

This handler processes events within PortaBilling:

  • SIPForwarder – this handler is used when an account is moved from one system to another. It provisions information about an account and/or the DID number location to the dispatching SBC in the Dual Version PortaSwitch deployment.

Supported event types

The ESPF is supplied with the following set of provisioning event types:

Name

Description

Variables

Inherited from Customer

AccessPolicy/Changed

An Internet access policy was updated

i_env, i_access_policy

AccessPolicy/Phase/New

A new Internet access policy phase was added

i_env, i_access_policy

AccessPolicy/Phase/Changed

An Internet access policy phase was updated

i_env, i_access_policy

AccessPolicy/Phase/Deleted

An Internet access policy phase was deleted

i_env, i_access_policy

Accessibility/Deleted

The usage charges record has been removed from the account’s product.

i_env, i_product, i_accessibility

Accessibility/Inserted

A usage charges record has been added to the account’s product.

i_env, i_product, i_accessibility

Account/ActivationDate/Changed

The activation date has been changed for an account. (Accounts.activation_date has been changed)

i_env, i_account, prev_activation_date, curr_activation_date

Account/AccessPolicy/Changed

The Internet access policy was updated for the account

i_env, i_account, i_access_policy

Account/Alias/Delete

An alias has been removed from an account.

i_env, i_master_account, id

Account/AvailableFundsAppear

An account’s available funds are restored when a debit account tops up the balance or when a postpaid customer pays their invoice. (Accounts.balance has been topped up from credit_limit.) I_account.

i_env, i_account

Y

Account/BalanceChanged

The balance of a debit or individual credit account has changed (e.g., a call has been charged, a refill has been received).

A customer’s balance has changed for postpaid customers.

i_env, i_account, prev_balance, curr_balance

Y

Account/Blocked

An account has been blocked. (Accounts.blocked set to ‘Y.’)

i_env, i_account

Account/CustomField/Changed

Custom information (e.g., ID card) has been added or changed for an account. (The Custom_Field_Values table has been updated for the account.)

i_env, i_account, field_name, prev_value, curr_value

Account/Discount/Changed

An account’s discount plan has changed.

i_env, i_account, prev_i_vd_plan, curr_i_vd_plan

Account/ExpirationDate/Changed

An account’s expiration date has changed. (Accounts.expiration_date has been changed.)

i_env, i_account, prev_expiration_date, curr_expiration_date

Account/FollowMe/Changed

An account’s follow-me setting has changed (the Follow_Me table has been updated).

i_env, i_account

Account/FollowMeNumber/Inserted

A new follow-me number has been added to an account.

i_env, i_account, i_follow_me, i_follow_me_number, curr_redirect_number

Account/FollowMeNumber/Changed

An account’s follow-me number has changed.

i_env, i_account, i_follow_me, i_follow_me_number, curr_redirect_number, prev_redirect_number

Account/FollowMeNumber/Deleted

An account’s follow-me number has been removed.

i_env, i_account, i_follow_me, i_follow_me_number, prev_redirect_number

Account/ID/Changed

An account’s ID has changed. (Account.id has been updated.)

i_env, i_account, prev_id, curr_id

Account/IPDeviceAssignment

An IP device has been assigned to an account (the UA_Links table has been updated).

i_env, i_account, prev_ua, prev_port, prev_config, i_ua, port, config

Account/New

A new account has been created.

i_env, i_account

Account/Password/Changed

An account’s password for the self-care interface has changed. (Accounts.password has been changed.)

i_env, i_account, prev_password, curr_password

Account/Product/Changed

Another product was assigned to the account.

An account’s product has changed. (Account.i_product has been updated.)

i_env, i_account, prev_product, curr_product

Account/ProductAddon/Changed

An account’s add-on product has been changed.

i_env, i_account, i_addon_product

Account/ProductAddon/Deleted

An add-on product has been removed from an account.

i_env, i_account, prev_i_addon_product

Account/ProductAddon/Inserted

A new add-on product has been added for an account.

i_env, i_account, curr_i_addon_product

Account/Service/QuotaAvailable

The account’s service usage quota has been restored (quota counter has been reset or user topped up their service wallet).

i_env, i_account, i_service, i_vd_dg

Account/Service/QuotaExceeded

An account has exceeded its service usage quota.

i_env, i_account, i_service, i_vd_dg

Account/Service/Msg/QuotaExceeded

An account’s service usage quota for messaging service type has expired

i_env, i_account, i_service

Account/Service/Netaccess/QuotaExceeded

An account’s Internet access quota has expired

i_env, i_account, i_service

Account/ServiceAttribute/Changed

A service feature has been enabled / disabled for an account (the Service_Attribute_Values table has been updated).

i_env, i_account, feature_name, attribute_name, old_value

Y

Account/ServiceFlags/Changed

An account’s service features have changed. (Accounts.service_flags has been updated.)

i_env, i_account, account_prev_service_flags

Y

Account/ServicePassword/Changed

An account’s service password has been changed.(Accounts.h323_password has been changed.)

i_env, i_account, prev_h323_pwd, curr_h323_pwd

Account/SIMCardAssignment

A SIM card has been assigned to, removed from or changed for an account.

i_env, i_account, prev_i_sim, i_sim

Account/Status/Changed

An account’s billing status has been changed or affected by the customer’s billing status.

A customer’s status has changed. (Customers.bill_status has changed.)

i_env, i_account, prev_status, new_status

Y

Account/Status/Closed

The status of the account has changed to Closed.

The account has been removed from the web interface. (Accounts.bill_status set to ‘C.’)

This event type appears when a customer is terminated.

i_env, i_account

Y

Account/Status/Exported

An account has been exported by Porter in Dual Version PortaSwitch.(Customers.bill_status set to E.)

i_env, i_account

Y

Account/Status/Imported

An account has been imported by Porter in Dual Version PortaSwitch.

i_env, i_account

Y

Account/Status/Suspend

An account’s status has changed to suspended because of a customer’s suspension.

Caused by: Customer has unpaid invoice.(Customers.bill_status set to ‘S.’)

i_env, i_account

Y

Account/Status/Unsuspend

An account has been unsuspended; due to removing of the customer’s suspension.

A customer’s account has been reinstated. (Customers.bill_status set to ‘O’ from ‘S.’)

i_env, i_account

Y

Account/Unblocked

An account has been unblocked. (Accounts.blocked set to ‘N.’)

i_env, i_account

Account/ZeroAvailableFunds

An account’s available funds have been depleted. (Accounts.balance has reached credit_limit [for credit accounts] or 0 [for debit accounts.])

i_env, i_account

Y

Connection/Changed

The connection information has been updated.

i_env, i_vendor, i_connection, prev_remote_ip

Connection/Deleted

The connection has been removed from the vendor.

i_env, i_vendor, i_connection, i_connection_type, prev_remote_ip

Connection/New

A new connection has been created for the vendor.

i_env, i_vendor, i_connection,

Custom/Jasper/CapReached

External event received from Jasper Platform.

i_env, i_account

Customer/AvailableFundsAppear

A customer has topped up his balance

i_env, i_customer

Customer/BalanceChanged

A customer’s balance has changed (e.g., a subscription charge has been applied or a refund has been issued)

i_env, i_customer, prev_balance, curr_balance

Customer/CustomField/ Changed

The data in a customer’s custom field has changed (the Custom_Field_Values table has been updated for the customer).

i_env, i_customer, field_name, prev_value, curr_value

Customer/Deleted

The customer’s record has been removed from the customer list.

i_env, i_customer, i_customer_class, name

Customer/Name/Changed

The customer’s name has changed.

i_env, i_customer, prev_name, curr_name

Customer/New

A new customer has been created.

i_env, i_customer

Customer/ServiceAttribute/Changed

A customer’s service setting has changed (the Service_Attribute_Values table has been updated).

i_env, i_customer, feature_name, attribute_name, old_value

Customer/ServiceFlags/Changed

A customer’s service features have changed. (Customers.service_flags has been updated.)

i_env, i_customer, prev_service_flags

Customer/Status/Activated

A customer’s record has been activated. (Customers.bill_status set to ‘O’ from ‘D.’)

i_env, i_customer

Customer/Status/Changed

A customer’s status has changed. (Customers.bill_status has been updated.)

i_env, i_customer, prev_status, new_status

Customer/Status/Closed

A customer has been terminated and their status changed to closed. (Customers.bill_status set to ‘C.’)

i_env, i_customer

Customer/Status/Deactivated

A customer’s record has been deactivated. (Customers.bill_status set to ‘D’ from ‘O.’)

i_env, i_customer

Customer/Status/Exported

A customer’s record status has changed. (Customers.bill_status set to E.)

i_env, i_customer, prev_status

Customer/Status/Imported

A customer’s record status has changed. (Customers.bill_status set to O.)

i_env, i_customer, new_status

Customer/Status/Suspend

A customer’s account has been suspended. (Customers.bill_status has been updated.)

i_env, i_customer

Customer/Status/Unsuspend

A customer’s account has been reinstated. (Customers.bill_status set to ‘O’ from ‘S.’)

i_env, i_customer

Customer/Unblocked

A customer’s account has been unblocked. (Customers.blocked set to ‘N.’)

i_env, i_customer

Customer/ZeroAvailableFunds

A customer’s available funds have been depleted. (Customers.balance has reached credit_limit.)

i_env, i_customer

CustomField/Changed

A customer’s custom data has changed (the Custom_Field_Values table has been updated).

i_account, i_env, curr_value, prev_value, field_name

CustomerSite/ServiceAttribute/Changed

A service configuration has changed for a customer class (the Service_Attribute_Values table has been updated).

i_env, i_customer_site, feature_name, attribute_name, old_value

DID/New

A new DID number has been added to the DID inventory.

i_env, number

DID/Status/Assigned

A DID number has been assigned to a customer.

i_env, number, prev_customer

DID/Status/Unassigned

A DID number has been removed from a customer.

i_env, number, prev_customer

DID/Status/Activated

A DID number has been assigned to a customer’s account ID.

i_env, number

DID/Status/Canceled

A DID number has been unassigned from a customer’s account ID.

i_env, number

DID/Status/Moved

A DID number has been moved to another installation as a result of provisioning.

i_env, number

DID/Deleted

A DID number has been removed from the DID inventory.

i_env, number

Invoice/Adjustment/ Changed

An invoice has been adjusted (refunded) by an administrator.

i_env, i_customer, invoice_number, amount_net, i_invoice_type, i_invoice_status, adjustments, prev_adjustments

Invoice/AmountPaid/ Changed

This is the amount a customer has paid. Use this event to track and provision:

– manual payment information; – partially paid invoice changes.

i_env, i_customer, invoice_number, amount_net, i_invoice_type, i_invoice_status, amount_paid, prev_amount_paid

Invoice/New

A new invoice has been generated.

i_env, i_customer, invoice_number, amount_net, i_invoice_type, i_invoice_status

Invoice/Status/Changed

An invoice has changed its status (e.g., from unpaid to paid, from unpaid to overdue).

Use this event to track and provision information:

  • about the payment statuses of generated invoices:

    • unpaid;

    • overdue;

    • paid;

    • partially paid;

    • do not pay;

    • no payment required;

    • previous balance remaining;

  • about the statuses of invoices that require administrator’s approval:

    • under review;

    • approved;

    • rejected.

Refer to the Invoice parameters and Invoices review chapters in the PortaBilling Administrator Guide for the description of these statuses.

Note that if a customer pays their invoice in installments, the Invoice/Status/Changed event occurs twice for this invoice:

  • first event – changes from unpaid to partially paid;

  • second – changes from partially paid to paid in full.

For example, a customer pays their $110 invoice in installments (e.g., $25+$20+$35+$30). Events occur when:

  • the first $25 payment is made: the invoice status changes from unpaid to partially paid;

  • the last $30 payment is made: the invoice status changes from partially paid to paid.

i_env, i_customer, invoice_number, amount_net, i_invoice_type, prev_i_invoice_status, i_invoice_status

IPDeviceProfile/New

A CPE profile has been created.

i_env, i_ua_profile

PaymentTransaction/New

A customer has made a credit card payment.

i_env, i_payment_transaction, test_mode, status, amount, iso_4217

PaymentTransaction/ResultCode/Changed

A transaction has either started or finished.

i_env, i_payment_transaction, test_mode, status, amount, iso_4217, result_code, prev_result_code

PaymentTransaction/Status/Changed

A transaction has changed its status.

i_env, i_payment_transaction, test_mode, prev_status, status, amount, iso_4217

Product/AccessPolicy/Changed

The Internet access policy has been updated for a product

i_env, i_product, i_access_policy

Product/Discount/Changed

A discount plan has been changed for a product or an add-on product.

i_env, i_product, prev_i_vd_plan, curr_i_vd_plan, addon_priority

Product/ServiceAttribute/Changed

A service feature has been enabled/disabled for a product or an add-on product.

i_env, i_product, feature_name, attribute_name, old_value

ServiceAttribute/Changed

A service feature has been enabled/disabled for either a product, add-on product, customer, or account.

i_savalue, i_foreign, i_attribute, old_value

Subscriber/Address/Changed

The address of a user registered as an account has changed.

i_env, i_subscriber, prev_baddr1… prev_baddr5, curr_baddr1 … curr_baddr5, prev_state, curr_state, prev_zip, curr_zip, prev_city, curr_city, prev_country, curr_country

Subscriber/ContactInfo/Changed

The account’s contact information has been changed.

i_env, i_subscriber, prev_phone1, curr_phone1, prev_phone2, curr_phone2, prev_cont1, curr_cont1, prev_cont2, curr_cont2, prev_faxnum, curr_faxnum, prev_email, curr_email, prev_bcc, curr_bcc

Subscriber/Name/Changed

The user’s name registered as an account has been changed.

i_env, i_subscriber, prev_companyname, curr_companyname, prev_salutation, curr_salutation, prev_firstname, curr_firstname, prev_midinit, curr_midinit, prev_lastname, curr_lastname

 

On this page