License Server Automations and Integrations


Automated Email Notifications for License Events

The License Server includes a robust notification system to keep you informed about critical license events. On the "Notifications" page, you can configure automatic email alerts to specific recipients. Supported events for licenses include: "generated, deleted, disabled, enabled, updated, validated, invalidated, expired, and will expire."

These emails are sent via your chosen SMTP server to the defined recipients. You can customize the message body in either plain text or HTML, with buttons available to generate sample messages. To personalize notifications, variables such as {licensee-email}, {licensee-name}, {licensee-key}, and {product-name} can be used in the "To," "Cc," "Bcc," "Subject," and "Message" fields. These variables are automatically replaced with actual values when the email is sent.

SMTP Server Configuration and Customization

The cloud-based License Server includes its own default SMTP server and sends emails from no-reply@cloud.license4j.com. However, for enhanced branding and deliverability, you can easily configure your own SMTP server on the settings page. This allows you to use your organization's mail server or integrate with public SMTP services like Gmail or Yahoo. Once configured, the cloud license server will connect to your specified SMTP server and send emails using the "from" address you've defined, ensuring consistency with your domain.

The message body uses a simple textarea for content creation. The email's content type is automatically determined: if the message starts with a <!DOCTYPE> tag, the email content type will be set to text/html; otherwise, it defaults to text/plain. For quick setup, predefined simple message contents are available and can be loaded by clicking the corresponding button. To test your email configuration without sending to actual recipients, the "Test Mail" button sends the email solely to your own administrative account, bypassing the addresses specified in the "To," "Cc," or "Bcc" fields.

Integrations

The license manager web application offers three primary integration types, all configured and displayed on a single, dedicated page for ease of management. These integrations are: Payment Processor Integration, REST API and Webhook Functionality.

Payment Processor Integration

LICENSE4J currently supports seamless integration with leading payment processors: Paddle, Stripe, and FastSpring. Each of these platforms leverages webhook functionality to automatically send notifications upon order creation and successful payment completion.

The designated webhook URL for receiving these notifications is https://cloud.license4j.com/v5/intg. It's crucial to set up this webhook URL within the settings of each respective payment processor's website to ensure proper routing of notifications. For enhanced security, LICENSE4J validates incoming webhook requests by relying on predefined IP address ranges used by Paddle, Stripe, and FastSpring, which are thoroughly documented on their individual websites. This ensures that only legitimate notifications from these trusted sources are processed.

To set up a new payment integration within LICENSE4J, click "Actions" and then select "New menu item," define the required fields, and save your changes. It's important to note that while you may have multiple products on your payment processor, you should add only one webhook destination on the payment processor's site. However, you must define separate integrations within LICENSE4J for each individual product. The selected template will be used to generate licenses with properties specified within that template.

Paddle

For Paddle, after defining your product and pricing, navigate to "Developer Tools" > "Notifications" on their website and click "New Destination." Enter the LICENSE4J destination URL and select the "transaction.completed" event. Obtain your API key from "Developer Tools" > "Authentication." LICENSE4J uses this API key to retrieve customer information (name and email) after the "transaction.completed" event, as Paddle sends only a unique customer ID. Remember to save this API key on the LICENSE4J settings page.

Stripe

To configure Stripe webhooks: Log in to your Stripe account. Go to "Developers" > "Webhooks." Click "Add destination." On the first page, select "invoice.paid" and "checkout.session.completed" as event types. On the second page, enter the LICENSE4J webhook URL. LICENSE4J requires a Stripe API key for one-time payments, as product and customer details are not included by default in their webhook payloads. The API key is used to extend the response and retrieve this necessary information. Save this key on the settings page.

FastSpring

For FastSpring, log in to your account, navigate to "Developers" > "Webhooks," click the "Configuration" tab, and then "Add URL Endpoint." Enter the LICENSE4J URL and choose the "order.completed" event type. No API key is required for FastSpring, as it includes customer and product details directly in its webhook notifications.

Secure Webhook Notifications from LICENSE4J Cloud Servers

Webhook notifications from LICENSE4J Cloud servers originate from a designated IP address of cloud.license4j.com. For enhanced security, it's advisable to configure your webhook handler to accept requests exclusively from this IP address, thereby preventing unauthorized access.

Each webhook request includes a crucial security feature: a header labeled "LICENSE4J-Signature." This signature is generated using the HMAC SHA256 algorithm with a secret key provided in your webhook configuration.

To ensure the integrity and authenticity of the webhook, you must implement a verification process. This involves recalculating the signature using the received data and your corresponding secret key. The newly generated signature must then be compared with the value in the "LICENSE4J-Signature" header. A match confirms the request is legitimate and unaltered, a vital step in securing your application and processing only valid webhook requests. 

// an example webhook payload
{
    "event": "license.generated",
    "time": "2025-01-01 10:10:11",
    "data": {
        "id": 1179014318968977348,
        "productId": 1446131546753861138,
        "productName": "Example Product 0",
        "licensekey": "MA2G7-PB9E3-69M4P-P557F-JCGCR",
        "licensetype": "Floating",
        "fullname": "Francine Hickey112",
        "email": "francine@optisoft.com",
        "company": "OptiSoft2",
        "maxAllowedUsage": 1,
        "validDays": 365,
        "features": "",
        "dateCreated": "2025-01-05 20:49:53",
        "dateUpdated": "2025-01-14 01:31:17",
        "dateExpires": null
    }
}


License Management Operations via REST API

LICENSE4J provides a dedicated REST API for comprehensive license management on the license server. This API empowers you to retrieve, create, update, and delete licenses, offering full control over your licensing operations.

To utilize the REST API, you'll need to generate a unique API key for each product you wish to manage. This is done on the "Automation > Integrations" page within the LICENSE4J platform. The API key must be transmitted in a header named X-API-KEY. For enhanced security and organization, each API key is product-specific, ensuring that access for license management is precisely restricted to its designated product.

Retrieve Licenses via REST API

To retrieve licenses from the server, use the following endpoint:
This API function returns a JSON-formatted list of license objects. If no query parameters are provided, it retrieves all licenses in the system. However, by specifying parameters like licensekey, email, company, or licensetype, you can filter the results to find specific licenses. For example, providing an email parameter will return only licenses associated with that email address, enabling targeted searches and streamlined license management. 
{
        "id": 1179014318968977348,
        "productId": 1446131546753861138,
        "productName": "Example Product 0",
        "licensekey": "MA2G7-PB9E3-69M4P-P557F-JCGCR",
        "licensetype": "Floating",
        "fullname": "Francine Hickey112",
        "email": "francine@optisoft.com",
        "company": "OptiSoft2",
        "maxAllowedUsage": 1,
        "validDays": 365,
        "features": "",
        "dateCreated": "2025-01-05 20:49:53",
        "dateUpdated": "2025-01-14 01:31:17",
        "dateExpires": null
    },
    {
        "id": 1182657212911119418,
        "productId": 1446131546753861138,
        "productName": "Example Product 0",
        "licensekey": "3BECB-YB4Y8-YUWKZ-NJ8ZJ-NAR9R",
        "licensetype": "Floating",
        "fullname": "James Cullen1121",
        "email": "james@axiom.com",
        "company": "Axiom 2",
        "maxAllowedUsage": 1,
        "validDays": 365,
        "features": "",
        "dateCreated": "2025-01-05 20:49:52",
        "dateUpdated": "2025-01-14 01:54:16",
        "dateExpires": null
    }
]


Generate License via REST API

To generate a new license, submit a POST request to the following endpoint:
You'll need to create a JSON request body that adheres to a specific structure (as detailed in the API documentation or provided examples). Ensure all necessary fields for the license you're generating are included, following the required data types and formats for a successful transaction. 
{
    "licensetype": "FLOATING", // required, values: NODELOCKED or FLOATING
    "fullname": "John Doe", // optional, string
    "email": "john@example.com", // optional, string
    "company": "ACME Comp.", // optional, string
    "maxAllowedUsage": 1, // required, integer
    "validDays": 365, // required, integer (0 for perpetual non-expiring licenses)
    "keyCharacterSet": "SAFE", // required, values: SAFE NUMBERS LETTERS NUMBERS_AND_LETTERS or any custom characters minimum 10
    "keyFormat": "LENGTH25_GROUP5" // required,
                        // values: LENGTH25_GROUP5 LENGTH20_GROUP5 LENGTH20_GROUP4 LENGTH16_GROUP4 or format like ?????-?????-?????
}

Upon successful execution, the system will return a license object in JSON format. This output will mirror the structure used when retrieving licenses, ensuring consistent data representation for easy handling and manipulation. 
{
    "id": 1179014318968977348,
    "productId": 1446131546753861138,
    "productName": "Example Product 0",
    "licensekey": "MA2G7-PB9E3-69M4P-P557F-JCGCR",
    "licensetype": "Floating",
    "fullname": "Francine Hickey112",
    "email": "francine@optisoft.com",
    "company": "OptiSoft2",
    "maxAllowedUsage": 1,
    "validDays": 365,
    "features": "",
    "dateCreated": "2025-01-05 20:49:53",
    "dateUpdated": "2025-01-14 01:31:17",
    "dateExpires": null
}


Update License via REST API

To update an existing license, send a PUT request to the following endpoint:
To initiate a license update, you'll need to submit a license request object containing the license key. Upon processing, all properties defined within this object will be updated accordingly. This offers the flexibility to modify any field associated with the license, including its type. You can even change the license key itself during this process, and you have the option to use different character sets for the new key. 
{
    "licensekey": "12345-12345-12345-12345", // required
    "licensetype": "FLOATING", // optional, values: NODELOCKED or FLOATING
    "fullname": "John Doe", // optional, string
    "email": "john@example.com", // optional, string
    "company": "ACME Comp.", // optional, string
    "maxAllowedUsage": 1, // optional, integer
    "validDays": 365, // optional, integer (0 for perpetual non-expiring licenses)
    "keyCharacterSet": "SAFE", // optional, values: SAFE NUMBERS LETTERS NUMBERS_AND_LETTERS or any custom characters minimum 10
    "keyFormat": "LENGTH25_GROUP5" // optional,
                            // values: LENGTH25_GROUP5 LENGTH20_GROUP5 LENGTH20_GROUP4 LENGTH16_GROUP4 or format like ?????-?????-?????
}


Delete License via REST API

To delete an existing license, send a DELETE request to the following endpoint with "licensekey" query parameter:
The system performs a search for the specified license key within the database. If the license key is located, it is promptly removed from the records. Upon successful completion of this process, the system responds with an HTTP 200 status code, indicating that the operation was successful. This ensures that the user is informed of the successful deletion of the license key.