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.

PortaBilling ESPF supports these HTTP authentication schemes:

The authentication is done with user ID and password.

Credentials string is constructed by joining the username and the password with a single colon (":"). The result is then base64 encoded.

For example, let’s say that user ID is username and the password is secret (e.g., username:secret). The authorization header then looks as follows:

Authorization: Basic dXNlcm5hbWU6c2VjcmV0

The Application receives the request, decodes the base64-encoded user ID and password. It compares the decoded credentials username:secret with the ones that are stored in the Application’s database. If they match, the authorization is passed.

The authentication is done with custom type and credentials;

The Authorization header contains the name of a custom authentication scheme and credentials as it is configured in PortaBilling.

For example, let’s say that the custom type is Plain and the password is passexample. The authorization header then looks as follows:

Authorization: Plain passexample

The Application receives the request, compares the authentication schema and credentials with the ones that are stored in the Application’s database. If they match, the authorization is passed.

The authentication is done authenticate by signature key and key ID.

Credentials string is constructed of the originating date (the value from the Date header), signature key, and signature key ID.

The Date header is used to form a signing string. This signing string is then signed with the signature key to make a signature. The HMAC-SHA1 algorithm (Hash-based Message Authentication Code using the SHA1 hash function) is used to sign the signing string with the key.

For example, let’s say that the signature key is signature, the key ID is test and the Date header is Thu, 12 Apr 2018 15:24:00 GMT. The authorization header then looks as follows:

Authorization: Signature keyId="test",algorithm="hmac-sha1",signature="+IkiEg9UkyA+gh+pcI64iti

The Application receives the request, takes the value from the Date header field, and verifies the value from the key ID field. The Application then takes the key value from the Application’s database and runs the algorithm to calculate the signature. The Application compares the obtained signature value with the one that is received in the Authorization header. If they match, the authorization is passed.

Authentication is done using the JWT-encoded (JSON Web Token) access token.

The Authorization header is in the following format:

Authorization: Bearer <token>

An access token is an encrypted string, usually generated by the server in response to a login request and used in subsequent requests to protected resources (e.g., API). The "Bearer" scheme can be understood as "give access to the bearer of this token".

A JWT token consists of three base64-encoded parts separated by dots: <header>.<payload>.<signature>

The header includes the token type (JWT) and the signing algorythm (e.g., HMACSHA256).

The payload contains the claims. This is the information about the user and additional data. In PortaBilling, the claims are the i_env value and the token expiration time defined in the Unix Time format.

The signature part is used to verify that the message wasn’t changed along the way and that the token sender is who they says they are. It includes the encoded header and payload, a signature key and is signed using the signing algorithm. A signature key is defined in the BearerAuth.Key option on the Configuration server.

To put it all together, let’s say the signature key is superkey, the payload values are: i_env=3 and the expiration time is 1560338716 (Wed Jun 12 14:25:16 2019 EEST). The signing algorithm is HMACSHA256. The authorization header then looks as follows:

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJpX2VudiI6MywiRXhwIjoxNTYwMzQyMzE2fQ.PONYERv3xYs5g--XwbflOcaWddSuUNt7hAQqvoEcO4Q

The ESPF and the Application must know the signature key. When the Application receives the request, it:

• captures the value from the Authorization header;
• strips the "Bearer" prefix before the token;
• runs the same signature algorithm to receive the signature value;
• compares the obtained signature’s own hashing operation with the signature on the token itself.

If the signatures match, authorization is successful.