Receiving provisional events

The ESPF sends provisioning events in POST requests with the content in the JSON format. Requests are sent in asynchronous mode with the average number of 10 requests per second.

POST requests are sent to the Application’s URL. We recommend using the HTTPS transport protocol since it ensures that the communication between PortaBilling and the application is secure.

Sending parameters such as the Application’s URL, HTTP authorization information are defined for the ESPF on the PortaBilling Configuration server. PortaBilling administrator provides these data for developers who create an external application.

The POST request contains the following mandatory headers:

• Date – this is the originating date and time of the request message in the HTTP date format;
• Content-Type – this is the media body type of the request (e.g., application/json).
• Authorization – this is authentication information provided by PortaBilling to authenticate itself with the Application. This header contains the authentication method (basic, custom or signature) followed by credentials.The default method is Basic. This means that PortaBilling provides base64-encoded user ID and password in the Authorization header field.

The body of the POST request contains:

• event_type – this is the type of event (created, updated, deleted) that has been applied to a specific entity in PortaBilling such as:
  • an account,
  • a customer,
  • an invoice,
  • a DID number;
• variables – this is the unique ID of the entity that has been modified in PortaBilling. These are: i_account / i_customer / i_invoice / number (for a DID).
• i_event – this is the unique identifier of the event. The Application uses this ID to recognize whether it is a new request or a repeat request and adjust the provisioning flow.

In PortaBilling, an account record stores information about subscriber’s configuration. For compliance with external systems, changes in account’s configuration are reflected as events of a Subscriber group. A customer record in PortaBilling stores general information (e.g., invoicing, taxation, etc.) about the owner of account(s).

Here is an example of the POST request that is sent to the Application:

The Application responds with the HTTP Status Codes. Once a response is received, the ESPF acts as follows:

• 200 OK – the event has been received. The ESPF removes the event from the provisioning queue.
• 4xx Client Error (e.g., 400 Bad Request) – the event must not be provisioned. The ESPF removes the event from the provisioning queue.
• Other status code – an issue appeared during provisioning. The ESPF re-sends the event.
• If no response is received from the Application during the timeout (300 seconds by default) – the ESPF re-sends the event to the Application. Please make sure your application can accept the same provisioning event multiple times.

Your external system can process provisioning requests synchronously and asynchronously. When processing data synchronously, a system processes a request immediately upon receipt and sends the provisioning results to the Application. Asynchronous data processing means that a system accepts a request and sends notifications with the provisioning status to your Application (e.g., an hour later).

Regardless of the data processing mode, once the Application receives a response from the external system, it can store the provisioning status for an account in PortaBilling. The Application sends the API request with the account’s provisioning status to the ESPF.

Please note that the ESPF only interacts with the Application. It considers that the external system (e.g., HSS) has been successfully provisioned once the 200 OK is received. Therefore, in case of provisioning issues between the Application and the external system, make sure that the Application replies with the proper status code.