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 as plain text
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
Webhook Request
Request Headers
Signature Verification
All webhook requests include anX-Signature header containing an HMAC SHA256 signature. You should verify this signature to ensure the request is from Komerza.
Signature Calculation:
Payload Structure
The webhook receives a JSON payload with the following structure:Payload Fields
The unique identifier of your store
The unique identifier of the customer who made the purchase
The unique identifier of the specific line item in the order
The unique identifier of the product being delivered
The unique identifier of the product variant being delivered
The quantity of items purchased for this line item
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 must respond with plain text (text/plain) containing the delivery content. This will be displayed to the customer exactly as returned.
Response Requirements
Must be
text/plainMust be
200 for successful delivery. Any other status code will be treated
as a failure and trigger retry logic.The actual delivery content to show the customer. Can be multi-line. Maximum
recommended length is 8,192 characters.
Example Implementations
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.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
Error Handling
Common Error Scenarios
Invalid Signature (401)
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)
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)
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
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
Testing
Test Webhook Locally
Use a tool like ngrok or cloudflared to expose your local development server:Manual Testing
You can manually test your webhook endpoint by simulating a request:Production Testing
- 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