Events API
Webhooks

13min
Events are exposed and dispatched through our webhooks service where the vendor platform user can configure an endpoint listener and a list of events happening in your LicenseSpring account which will be dispatched to that endpoint URL. HTTPS is used to send webhook events to your app as a JSON payload.
This is Enterprise feature only. For more information, please contact sales.
Setup
Webhooks can be configured in the vendor platform under Settings > Webhooks.
To start receiving webhook events in your app you need to create and register a webhook endpoint using the webhooks dashboard. Set up an HTTPS endpoint function that can accept webhook requests so that it handles POST requests with a JSON payload consisting of an event object.
Webhook configuration panel
﻿
Along with configuration view, the webhooks panel will display history of sent events and option to rollover the secret key needed to verify the webhook data authenticity.
Webhook details view
﻿
Instructions
Handle duplicate events
Webhook endpoints might occasionally receive the same event more than once. You can guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.
Only listen to event types your integration requires
Configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra events (or all events) puts undue strain on your server and we don’t recommend it.
Receive events with an HTTPS server
If you use an HTTPS URL for your webhook endpoint, LicenseSpring validates that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.
Roll endpoint signing secrets periodically
The secret key used for verifying that events come from LicenseSpring is rollable. You can choose to immediately expire the current secret key or delay its expiration for up to 24 hours to allow yourself time to update the verification code on your server. During this time, multiple secrets are active for the endpoint. LicenseSpring generates one signature per secret until expiration. To keep them safe, we recommend that you roll secret keys periodically, or when you suspect a compromised secret key.
Verify events are sent from LicenseSpring
Verify webhook signatures to confirm that received events are sent from LicenseSpring. LicenseSpring signs webhook events it sends to your endpoints by including a signature in each event’s Licensespring-Signature header. This allows you to verify that the events were sent by LicenseSpring, not by a third party. You can verify signatures either using our official libraries, or verify manually using your own solution. The secret key for each endpoint can be found in the webhooks dashboard.
Verifying signatures using our official SDKs
At the moment, verification of a webhook signature is included in Python SDK only.
You perform the verification by providing the event payload, the Licensespring-Signature header, and the endpoint’s secret. If verification fails, you get an error. LicenseSpring requires the raw body of the request to perform signature verification. If you’re using a framework, make sure it doesn’t manipulate the raw body. Any manipulation to the raw body of the request causes the verification to fail.
Python
from licensespring.webhook import Webhook
from licensespring.webhook.error import SignatureVerificationError
from flask import Flask, request

# Using Flask
# Signing key is set as LICENSESPRING_SIGNING_SECRET env var
@app.route('/licensespring/webhooks/', methods=['POST'])
def licensespring_webhooks():
    licensespring_signature = request.headers.get('Licensespring-Signature')

    try:
        event = Webhook.get_event(
            payload=request.get_data(as_text=True),
            sig_header=licensespring_signature,
            secret=os.environ['LICENSESPRING_SIGNING_SECRET'])
    except SignatureVerificationError:
        return ('Signature is not valid.', 400)

    # Handle the event
    print('Received event {} ({}) from LS with data: {}'.format(
      event.get('event'), 
      event.get('id'), 
      event.get('data')
    ))

    return 'Webhook processed.'
from licensespring.webhook import Webhook
from licensespring.webhook.error import SignatureVerificationError
from flask import Flask, request

# Using Flask
# Signing key is set as LICENSESPRING_SIGNING_SECRET env var
@app.route('/licensespring/webhooks/', methods=['POST'])
def licensespring_webhooks():
    licensespring_signature = request.headers.get('Licensespring-Signature')

    try:
        event = Webhook.get_event(
            payload=request.get_data(as_text=True),
            sig_header=licensespring_signature,
            secret=os.environ['LICENSESPRING_SIGNING_SECRET'])
    except SignatureVerificationError:
        return ('Signature is not valid.', 400)

    # Handle the event
    print('Received event {} ({}) from LS with data: {}'.format(
      event.get('event'), 
      event.get('id'), 
      event.get('data')
    ))

    return 'Webhook processed.'
﻿
Verifying signatures manually
The Licensespring-Signature header included in each signed event contains a timestamp and one or more signatures that you must verify. The timestamp is prefixed by t=, and each signature is prefixed by a scheme. Schemes start with v, followed by an integer. Currently, the only valid live signature scheme is v1.
Text
t=1706880193,v1=b5125c98c3b58e09bdbe3615057ee2b22f421e67d9ee5791cc7d2d43bfd6363f
t=1706880193,v1=b5125c98c3b58e09bdbe3615057ee2b22f421e67d9ee5791cc7d2d43bfd6363f
﻿
LicenseSpring generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To prevent downgrade attacks, ignore all schemes that are not v1.
You can have multiple signatures with the same scheme-secret pair when you roll an endpoint’s secret, and keep the previous secret active for up to 24 hours. During this time, your endpoint has multiple active secrets and LicenseSpring generates one signature for each secret.
To create a manual solution for verifying signatures, you must complete the following steps:
Step 1: Extract the timestamp and signatures from the header
Split the header using the , character as the separator to get a list of elements. Then split each element using the = character as the separator to get a prefix and value pair.
The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature (or signatures). You can discard all other elements.
Step 2: Prepare the  string
The signed_payload string is created by concatenating:
The timestamp (as a string)
The character .
The actual JSON payload (that is, the request body)
Step 3: Determine the expected signature
Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.
Step 4: Compare the signatures
Compare the signature (or signatures) in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
Python
JS
import hmac
import json
import time
from hashlib import sha256


def secure_compare(val1, val2):
    return hmac.compare_digest(val1, val2)


class SignatureVerificationError(Exception):
    def __init__(self, message, sig_header, payload):
        self.message = message
        self.sig_header = sig_header
        self.payload = payload

    def __str__(self):
        return self.message

    def __repr__(self):
        return str(self)


class WebhookSignature:
    EXPECTED_SCHEME = "v1"

    @staticmethod
    def compute_signature(payload, secret):
        mac = hmac.new(
            secret.encode("utf-8"),
            msg=payload.encode("utf-8"),
            digestmod=sha256,
        )
        return mac.hexdigest()

    @staticmethod
    def get_timestamp_and_signatures(header, scheme):
        list_items = [i.split("=", 2) for i in header.split(",")]
        timestamp = int([i[1] for i in list_items if i[0] == "t"][0])
        signatures = [i[1] for i in list_items if i[0] == scheme]
        return timestamp, signatures

    @classmethod
    def verify_header(cls, payload, header, secret, tolerance=None):
        try:
            timestamp, signatures = cls.get_timestamp_and_signatures(
                header, cls.EXPECTED_SCHEME
            )
        except Exception:
            raise SignatureVerificationError(
                "Unable to extract timestamp and signatures from header",
                header,
                payload,
            )

        if not signatures:
            raise SignatureVerificationError(
                "No signatures found with expected scheme {}".format(
                    cls.EXPECTED_SCHEME
                ),
                header,
                payload,
            )

        signed_payload = "%d.%s" % (timestamp, payload)
        expected_sig = cls.compute_signature(signed_payload, secret)
        if not any(secure_compare(expected_sig, s) for s in signatures):
            raise SignatureVerificationError(
                "No signatures found matching the expected signature for payload",
                header,
                payload,
            )

        if tolerance and timestamp < time.time() - tolerance:
            raise SignatureVerificationError(
                "Timestamp outside the tolerance zone ({})".format(timestamp),
                header,
                payload,
            )

        return True


class Webhook:
    DEFAULT_TOLERANCE = 300  # 5 minutes

    @staticmethod
    def get_event(payload, sig_header, secret, tolerance=DEFAULT_TOLERANCE):
        WebhookSignature.verify_header(payload, sig_header, secret, tolerance)
        return json.loads(payload)


event = Webhook.get_event(
    payload=_PAYLOAD_GOES_HERE_,
    sig_header=_LICENSESPRING_SIGNATURE_HEADER_GOES_HERE_,
    secret=_SIGNING_KEY_GOES_HERE_,
    tolerence=_OPTIONAL_TOLERENCE_GOES_HERE_,
)
import hmac
import json
import time
from hashlib import sha256


def secure_compare(val1, val2):
    return hmac.compare_digest(val1, val2)


class SignatureVerificationError(Exception):
    def __init__(self, message, sig_header, payload):
        self.message = message
        self.sig_header = sig_header
        self.payload = payload

    def __str__(self):
        return self.message

    def __repr__(self):
        return str(self)


class WebhookSignature:
    EXPECTED_SCHEME = "v1"

    @staticmethod
    def compute_signature(payload, secret):
        mac = hmac.new(
            secret.encode("utf-8"),
            msg=payload.encode("utf-8"),
            digestmod=sha256,
        )
        return mac.hexdigest()

    @staticmethod
    def get_timestamp_and_signatures(header, scheme):
        list_items = [i.split("=", 2) for i in header.split(",")]
        timestamp = int([i[1] for i in list_items if i[0] == "t"][0])
        signatures = [i[1] for i in list_items if i[0] == scheme]
        return timestamp, signatures

    @classmethod
    def verify_header(cls, payload, header, secret, tolerance=None):
        try:
            timestamp, signatures = cls.get_timestamp_and_signatures(
                header, cls.EXPECTED_SCHEME
            )
        except Exception:
            raise SignatureVerificationError(
                "Unable to extract timestamp and signatures from header",
                header,
                payload,
            )

        if not signatures:
            raise SignatureVerificationError(
                "No signatures found with expected scheme {}".format(
                    cls.EXPECTED_SCHEME
                ),
                header,
                payload,
            )

        signed_payload = "%d.%s" % (timestamp, payload)
        expected_sig = cls.compute_signature(signed_payload, secret)
        if not any(secure_compare(expected_sig, s) for s in signatures):
            raise SignatureVerificationError(
                "No signatures found matching the expected signature for payload",
                header,
                payload,
            )

        if tolerance and timestamp < time.time() - tolerance:
            raise SignatureVerificationError(
                "Timestamp outside the tolerance zone ({})".format(timestamp),
                header,
                payload,
            )

        return True


class Webhook:
    DEFAULT_TOLERANCE = 300  # 5 minutes

    @staticmethod
    def get_event(payload, sig_header, secret, tolerance=DEFAULT_TOLERANCE):
        WebhookSignature.verify_header(payload, sig_header, secret, tolerance)
        return json.loads(payload)


event = Webhook.get_event(
    payload=_PAYLOAD_GOES_HERE_,
    sig_header=_LICENSESPRING_SIGNATURE_HEADER_GOES_HERE_,
    secret=_SIGNING_KEY_GOES_HERE_,
    tolerence=_OPTIONAL_TOLERENCE_GOES_HERE_,
)
﻿
Preventing replay attacks
A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, LicenseSpring includes a timestamp in the Licensespring-Signature header. Because this timestamp is part of the signed payload, it’s also verified by the signature, so an attacker can’t change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.
Our SDKs have a default tolerance of 5 minutes between the timestamp and the current time. You can change this tolerance by providing an additional parameter when verifying signatures.
Quickly return a 2xx response
Quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout (timeout occurs after 20 seconds). In the event of a timeout the webhook will be logged with 408 Request Timeout status code.
Updated 06 Feb 2024
Did this page help you?
Events API
Events list