Dynamic Delivery - Komerza Documentation

Overview

Dynamic Delivery allows you to programmatically handle product fulfillment by implementing a webhook endpoint that receives order information and returns delivery content. This is ideal for delivering digital products, license keys, game codes, or integrating with external fulfillment systems. When a customer purchases a product with dynamic delivery enabled, Komerza immediately sends a POST request to your configured webhook URL with order details, and your endpoint responds with the content to deliver to the customer.

Dynamic Delivery is configured per product variant in your product settings under delivery methods.

Use Cases

Digital Products

Deliver license keys, download links, or access codes in real-time

Third-Party Integration

Connect with external fulfillment systems or inventory management

Custom Logic

Implement complex delivery rules based on customer, product, or order data

Game Codes

Deliver game keys, activation codes, or in-game items automatically

How It Works

Customer Purchases - A customer completes checkout for a product with dynamic delivery enabled
Webhook Triggered - Komerza sends a POST request to your configured webhook URL
Your Response - Your endpoint processes the request and returns the delivery content
Customer Receives - The returned content is delivered to the customer, either as a single item or as one item per unit - see Response Format

Configuration

Setting Up Dynamic Delivery

Navigate to your product in the Komerza Dashboard
Select the variant you want to configure
Choose Dynamic Delivery as the delivery method
Enter your webhook endpoint URL
Generate and save your webhook secret

Keep your webhook secret secure. It’s used to verify that requests are genuinely from Komerza.

Webhook Request

Request Headers

Content-Type: application/json
Accept: application/json
User-Agent: Komerza/1.0
X-Signature: <HMAC-SHA256-SIGNATURE>

Signature Verification

All webhook requests include an X-Signature header containing an HMAC SHA256 signature. You should verify this signature to ensure the request is from Komerza. Signature Calculation:

HMAC-SHA256(secret, request_body) -> HEX encoded

const crypto = require("crypto");

function verifySignature(secret, body, signature) {
  const calculatedSignature = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex")
    .toUpperCase();

  return calculatedSignature === signature.toUpperCase();
}

// Express middleware example
app.use("/webhook", express.raw({ type: "application/json" }));

app.post("/webhook", (req, res) => {
  const signature = req.headers["x-signature"];
  const body = req.body.toString("utf8");

  if (!verifySignature(process.env.WEBHOOK_SECRET, body, signature)) {
    return res.status(401).send("Invalid signature");
  }

  // Process webhook...
});

import hmac
import hashlib

def verify_signature(secret: str, body: str, signature: str) -> bool:
    calculated_signature = hmac.new(
        secret.encode('utf-8'),
        body.encode('utf-8'),
        hashlib.sha256
    ).hexdigest().upper()

    return calculated_signature.upper() == signature.upper()

# Flask example
from flask import Flask, request, abort

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    body = request.get_data(as_text=True)

    if not verify_signature(os.environ['WEBHOOK_SECRET'], body, signature):
        abort(401, 'Invalid signature')

    # Process webhook...

<?php

function verifySignature($secret, $body, $signature) {
    $calculatedSignature = strtoupper(
        hash_hmac('sha256', $body, $secret)
    );

    return hash_equals($calculatedSignature, strtoupper($signature));
}

// Usage
$signature = $_SERVER['HTTP_X_SIGNATURE'];
$body = file_get_contents('php://input');

if (!verifySignature($_ENV['WEBHOOK_SECRET'], $body, $signature)) {
    http_response_code(401);
    die('Invalid signature');
}

// Process webhook...

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "io"
    "net/http"
    "strings"
)

func verifySignature(secret, body, signature string) bool {
    h := hmac.New(sha256.New, []byte(secret))
    h.Write([]byte(body))
    calculatedSignature := strings.ToUpper(hex.EncodeToString(h.Sum(nil)))

    return calculatedSignature == strings.ToUpper(signature)
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    signature := r.Header.Get("X-Signature")
    body, _ := io.ReadAll(r.Body)

    if !verifySignature(os.Getenv("WEBHOOK_SECRET"), string(body), signature) {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    // Process webhook...
}

using System.Security.Cryptography;
using System.Text;

public static bool VerifySignature(string secret, string body, string signature)
{
    var secretBytes = Encoding.UTF8.GetBytes(secret);
    using var hmac = new HMACSHA256(secretBytes);
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(body));
    var calculatedSignature = Convert.ToHexString(hash);

    return calculatedSignature.Equals(signature, StringComparison.OrdinalIgnoreCase);
}

// ASP.NET Core example
[HttpPost("webhook")]
public async Task<IActionResult> Webhook()
{
    using var reader = new StreamReader(Request.Body);
    var body = await reader.ReadToEndAsync();
    var signature = Request.Headers["X-Signature"].ToString();

    if (!VerifySignature(_configuration["WebhookSecret"], body, signature))
    {
        return Unauthorized("Invalid signature");
    }

    // Process webhook...
}

Payload Structure

The webhook receives a JSON payload with the following structure:

{
  "storeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customerId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "lineItemId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "productId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "variantId": "8f7e6d5c-4b3a-2918-7654-3210fedcba98",
  "quantity": 1,
  "order": {
    "id": "5f3a8b2c-1d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "totalPrice": 29.99,
    "currency": "USD",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "items": [
      {
        "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
        "productName": "Premium License",
        "variantName": "1 Year",
        "quantity": 1,
        "price": 29.99
      }
    ],
    "createdAt": "2025-11-27T10:30:00Z"
  }
}

Payload Fields

string (uuid)

required

The unique identifier of your store

string (uuid)

required

The unique identifier of the customer who made the purchase

string (uuid)

required

The unique identifier of the specific line item in the order

string (uuid)

required

The unique identifier of the product being delivered

string (uuid)

required

The unique identifier of the product variant being delivered

integer

required

The quantity of items purchased for this line item

object

required

Complete order information including customer details, all items, and payment information. See the Order object in the API Reference for full schema details.

Webhook Response

Response Format

Your endpoint can answer in one of two ways. Which you choose matters when a single purchase covers more than one unit.

Plain text - one delivery

Respond with plain text (text/plain) containing the delivery content. It is shown to the customer exactly as returned.

HTTP/1.1 200 OK
Content-Type: text/plain

LICENSE-KEY-ABC123-XYZ789-PREMIUM
Download: https://example.com/download/abc123
Valid until: 2026-11-27

A plain-text body is always treated as one delivered item, however many lines it contains. That is deliberate: a multi-line body is usually one thing - an account with its password on the next line - and splitting it would hand the customer half a login.

Because a plain-text body is one delivery, a customer who buys a quantity of ten receives a single item. If you want them to receive ten, use the JSON form below.

JSON - one delivery per unit

Respond with a JSON object containing an items array, and each entry becomes a separate delivered item. Use this when a purchase of ten should hand over ten distinct keys rather than one block of text.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    "LICENSE-KEY-ABC123",
    "LICENSE-KEY-DEF456",
    "LICENSE-KEY-GHI789"
  ]
}

The request payload tells you how many to return: read the top-level quantity field (see Payload Fields) and return that many entries.

This form is required if resellers buy your stock in bulk. Buying stock up front only works when each unit arrives as its own item, so a supplier answering in plain text can only ever deliver one, and the rest of the purchase is refunded.

How the JSON form is detected, exactly:

The body must begin with { (after any leading whitespace) and parse as a JSON object containing an items array. Anything else is treated as plain text.
Entries that are JSON strings are delivered as-is. Entries of any other type - an object, for example - are delivered as their raw JSON.
Blank and whitespace-only entries are skipped. If that leaves no usable entries, the whole body is treated as plain text instead.

Response Requirements

string

required

text/plain for a single delivery, or application/json for the items form. The body is inspected either way, so a mislabelled content type does not by itself break delivery.

integer

required

Must be 200 for successful delivery. Any other status code will be treated as a failure and trigger retry logic.

string

required

The actual delivery content to show the customer. Can be multi-line. Each delivered item is stored up to 10,000 characters and anything beyond that is cut off, so keep individual items comfortably below it.

Example Implementations

const express = require("express");
const crypto = require("crypto");
const app = express();

// Important: Use raw body parser for signature verification
app.use("/webhook", express.raw({ type: "application/json" }));

app.post("/webhook", async (req, res) => {
  const signature = req.headers["x-signature"];
  const body = req.body.toString("utf8");

  // Verify signature
  if (!verifySignature(process.env.WEBHOOK_SECRET, body, signature)) {
    return res.status(401).send("Invalid signature");
  }

  // Parse the payload
  const payload = JSON.parse(body);

  // Generate or fetch delivery content based on your logic
  const licenseKey = await generateLicenseKey(
    payload.productId,
    payload.customerId,
  );
  const downloadUrl = await createDownloadLink(payload.variantId);

  // Return plain text delivery content
  res.setHeader("Content-Type", "text/plain");
  res
    .status(200)
    .send(
      `License Key: ${licenseKey}\n` +
        `Download: ${downloadUrl}\n` +
        `Valid for: 1 Year\n` +
        `Customer: ${payload.order.customer.email}`,
    );
});

function verifySignature(secret, body, signature) {
  const calculatedSignature = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex")
    .toUpperCase();
  return calculatedSignature === signature.toUpperCase();
}

app.listen(3000);

from flask import Flask, request, abort
import hmac
import hashlib
import json
import os

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    body = request.get_data(as_text=True)

    # Verify signature
    if not verify_signature(os.environ['WEBHOOK_SECRET'], body, signature):
        abort(401, 'Invalid signature')

    # Parse payload
    payload = json.loads(body)

    # Generate delivery content
    license_key = generate_license_key(payload['productId'], payload['customerId'])
    download_url = create_download_link(payload['variantId'])

    # Return plain text response
    response = f"""License Key: {license_key}
Download: {download_url}
Valid for: 1 Year
Customer: {payload['order']['customer']['email']}"""

    return response, 200, {'Content-Type': 'text/plain'}

def verify_signature(secret: str, body: str, signature: str) -> bool:
    calculated = hmac.new(
        secret.encode('utf-8'),
        body.encode('utf-8'),
        hashlib.sha256
    ).hexdigest().upper()
    return calculated == signature.upper()

if __name__ == '__main__':
    app.run(port=3000)

<?php

function verifySignature($secret, $body, $signature) {
    $calculated = strtoupper(hash_hmac('sha256', $body, $secret));
    return hash_equals($calculated, strtoupper($signature));
}

// Get raw POST body
$body = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

// Verify signature
if (!verifySignature($_ENV['WEBHOOK_SECRET'], $body, $signature)) {
    http_response_code(401);
    die('Invalid signature');
}

// Parse payload
$payload = json_decode($body, true);

// Generate delivery content
$licenseKey = generateLicenseKey($payload['productId'], $payload['customerId']);
$downloadUrl = createDownloadLink($payload['variantId']);

// Return plain text response
header('Content-Type: text/plain');
http_response_code(200);

echo "License Key: {$licenseKey}\n";
echo "Download: {$downloadUrl}\n";
echo "Valid for: 1 Year\n";
echo "Customer: {$payload['order']['customer']['email']}";

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
)

type Payload struct {
    StoreId    string `json:"storeId"`
    CustomerId string `json:"customerId"`
    ProductId  string `json:"productId"`
    VariantId  string `json:"variantId"`
    Quantity   int    `json:"quantity"`
    Order      struct {
        Customer struct {
            Email string `json:"email"`
        } `json:"customer"`
    } `json:"order"`
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    signature := r.Header.Get("X-Signature")
    body, _ := io.ReadAll(r.Body)

    // Verify signature
    if !verifySignature(os.Getenv("WEBHOOK_SECRET"), string(body), signature) {
        http.Error(w, "Invalid signature", http.StatusUnauthorized)
        return
    }

    // Parse payload
    var payload Payload
    json.Unmarshal(body, &payload)

    // Generate delivery content
    licenseKey := generateLicenseKey(payload.ProductId, payload.CustomerId)
    downloadUrl := createDownloadLink(payload.VariantId)

    // Return plain text response
    w.Header().Set("Content-Type", "text/plain")
    w.WriteHeader(http.StatusOK)
    fmt.Fprintf(w, "License Key: %s\n", licenseKey)
    fmt.Fprintf(w, "Download: %s\n", downloadUrl)
    fmt.Fprintf(w, "Valid for: 1 Year\n")
    fmt.Fprintf(w, "Customer: %s", payload.Order.Customer.Email)
}

func verifySignature(secret, body, signature string) bool {
    h := hmac.New(sha256.New, []byte(secret))
    h.Write([]byte(body))
    calculated := strings.ToUpper(hex.EncodeToString(h.Sum(nil)))
    return calculated == strings.ToUpper(signature)
}

func main() {
    http.HandleFunc("/webhook", webhookHandler)
    http.ListenAndServe(":3000", nil)
}

Honouring Quantity

The examples above return one delivery regardless of how many units were bought. To hand over one item per unit, read quantity from the payload and return that many entries.

@app.route('/webhook', methods=['POST'])
def dynamic_delivery():
    payload = json.loads(request.get_data(as_text=True))
    quantity = payload.get('quantity', 1)

    keys = [
        generate_license_key(payload['productId'], payload['customerId'])
        for _ in range(quantity)
    ]

    return jsonify({'items': keys}), 200

<?php
$payload = json_decode(file_get_contents('php://input'), true);
$quantity = $payload['quantity'] ?? 1;

$keys = [];
for ($i = 0; $i < $quantity; $i++) {
    $keys[] = generateLicenseKey($payload['productId'], $payload['customerId']);
}

header('Content-Type: application/json');
http_response_code(200);
echo json_encode(['items' => $keys]);

func handleWebhook(w http.ResponseWriter, r *http.Request) {
    var payload WebhookPayload
    json.NewDecoder(r.Body).Decode(&payload)

    quantity := payload.Quantity
    if quantity < 1 {
        quantity = 1
    }

    keys := make([]string, 0, quantity)
    for i := 0; i < quantity; i++ {
        keys = append(keys, generateLicenseKey(payload.ProductID, payload.CustomerID))
    }

    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    json.NewEncoder(w).Encode(map[string][]string{"items": keys})
}

Return exactly quantity entries. Returning fewer means the customer is charged for units they did not receive, and for a reseller buying stock the shortfall is refunded rather than delivered.

Timeout and Retry Logic

Timeout

Your webhook endpoint has 20 seconds to respond. If your endpoint doesn’t respond within this timeframe, the request will be considered failed and will be retried.

For operations that take longer than 20 seconds, consider using an asynchronous pattern: 1. Immediately return a success response 2. Process the delivery in the background 3. Use the Komerza API to update the delivery status when ready

Retry Policy

Komerza implements an automatic retry mechanism with exponential backoff for failed webhook deliveries:

Retry Attempts: 3 automatic retries
Backoff Strategy: Exponential (2^retry seconds)
- 1st retry: after 2 seconds
- 2nd retry: after 4 seconds
- 3rd retry: after 8 seconds

Circuit Breaker

To protect your endpoint from being overwhelmed, Komerza implements a circuit breaker:

Threshold: 5 consecutive failures
Break Duration: 30 seconds
Behavior: After 5 consecutive failures, requests are paused for 30 seconds before attempting again

Ensure your endpoint is highly available. Repeated failures may trigger the circuit breaker, temporarily preventing delivery webhooks from being sent.

Error Handling

Common Error Scenarios

Invalid Signature (401)

Cause: The signature verification failedSolution:

Verify you’re using the correct webhook secret
Ensure you’re reading the raw request body (not parsed JSON)
Check your HMAC implementation matches the algorithm (SHA256, HEX encoded)

Timeout (408)

Cause: Your endpoint didn’t respond within 20 seconds Solution: - Optimize your delivery generation logic - Use caching for frequently accessed data - Consider asynchronous processing for complex operations

Server Error (500)

Cause: Your endpoint returned an error response Solution: - Check your application logs for errors - Implement proper error handling and logging - Validate the payload structure before processing

Circuit Breaker Triggered

Cause: Too many consecutive failures (5+)Solution:

Check your server health and availability
Review error logs to identify the root cause
Implement health checks and monitoring
The circuit breaker will automatically reset after 30 seconds

Logging and Debugging

Komerza logs all webhook requests and responses for debugging purposes:

Request Body: Stored (truncated to 8,192 characters)
Response Body: Stored (truncated to 900 characters)
Response Code: Recorded for each attempt
Signature: Stored for verification

You can view these logs in your Komerza Dashboard under Webhook Execution Logs.

Testing

Test Webhook Locally

Use a tool like ngrok or cloudflared to expose your local development server:

# Start your local server
npm start  # or your framework's dev command

# In another terminal, start ngrok
ngrok http 3000

# Use the ngrok URL (e.g., https://abc123.ngrok.io/webhook) in your Komerza product configuration

Manual Testing

You can manually test your webhook endpoint by simulating a request:

# Generate signature
SECRET="your-webhook-secret"
PAYLOAD='{"storeId":"...","customerId":"...","order":{...}}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print toupper($2)}')

# Send test request
curl -X POST https://your-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

Production Testing

Test in your development/staging environment first before enabling dynamic delivery in production.

Create a test product with dynamic delivery enabled
Point it to your staging webhook endpoint
Make a test purchase (use test mode if available)
Verify the delivery content is generated correctly
Check webhook execution logs in your dashboard

Support

Help Center

Browse our knowledge base and guides

Discord Community

Get help from the community and Komerza team

System Status

Check webhook and API system status

Join our Telegram community for support

​Overview

​Use Cases

Digital Products

Third-Party Integration

Custom Logic

Game Codes

​How It Works

​Configuration

​Setting Up Dynamic Delivery

​Webhook Request

​Request Headers

​Signature Verification

​Payload Structure

​Payload Fields

​Webhook Response

​Response Format

​Plain text - one delivery

​JSON - one delivery per unit

​Response Requirements

​Example Implementations

​Honouring Quantity

​Timeout and Retry Logic

​Timeout

​Retry Policy

​Circuit Breaker

​Error Handling

​Common Error Scenarios

​Logging and Debugging

​Testing

​Test Webhook Locally

​Manual Testing

​Production Testing

​Support

Help Center

Discord Community

System Status

Telegram

Overview

Use Cases

How It Works

Configuration

Setting Up Dynamic Delivery

Webhook Request

Request Headers

Signature Verification

Payload Structure

Payload Fields

Webhook Response

Response Format

Plain text - one delivery

JSON - one delivery per unit

Response Requirements

Example Implementations

Honouring Quantity

Timeout and Retry Logic

Timeout

Retry Policy

Circuit Breaker

Error Handling

Common Error Scenarios

Logging and Debugging

Testing

Test Webhook Locally

Manual Testing

Production Testing

Support