Dynamic Product Delivery

The callback contract used by DYNAMIC products via dynamic_webhook

Overview

dynamic_webhook is not a normal Shoppex event webhook. It is a direct server-to-server callback that Shoppex sends when a DYNAMIC product is being fulfilled after a paid order.

Here’s how it works:

1. Create the product

   You create a product with type: "DYNAMIC", set dynamic_webhook, and keep the generated dynamic webhook signing secret.

2. Customer pays

   A customer pays for that product.

3. Shoppex calls your endpoint

   Shoppex sends POST to your dynamic_webhook URL.

4. Your server responds

   Your server returns delivery data, or explicitly acknowledges that it will fulfill the line item later.

5. Shoppex stores the result

   Shoppex either stores the delivered content or marks the line item as AWAITING_FULFILLMENT.

This page covers the callback contract for dynamic_webhook. For normal Shoppex event webhooks like order:paid, see Webhooks Overview and Webhook Events.

When Shoppex Calls It

Shoppex calls the dynamic_webhook URL during product fulfillment after the invoice reaches a paid/completed state. The customer buys your dynamic product, Shoppex marks the invoice as paid, starts fulfillment, calls your endpoint, and saves your response into the invoice delivery details.

Request

Shoppex sends:

• Method: POST
• Content-Type: application/json
• Body: JSON payload with invoice, product, shop, and line item data

Headers

Header	Description
Content-Type	Always application/json
X-Shoppex-Idempotency-Key	Stable delivery key for deduplication
X-Shoppex-Delivery-Id	Same value as the idempotency key
X-Shoppex-Timestamp	Unix timestamp in seconds used in the v2 signature
X-Shoppex-Signature-V2	Timestamped HMAC-SHA256 signature: v1,t=<timestamp>,h=<hex>
X-Shoppex-Signature-V2-Algorithm	HMAC-SHA256 when a v2 signature is present
X-Shoppex-Signature	Deprecated legacy HMAC-SHA512 body-only signature
X-Shoppex-Signature-Algorithm	Deprecated legacy value HMAC-SHA512

Signing Secret

Dynamic Product Delivery has its own signing secret on the product. It is separate from normal Shoppex event webhook secrets.

• Normal event webhooks: create the endpoint in Settings -> Webhooks and use that endpoint secret.
• Dynamic product delivery: set dynamic_webhook on the product and use the product’s dynamic webhook signing secret.

When creating or updating a dynamic product through the Developer API, pass dynamic_webhook_secret to set your own secret. If you set dynamic_webhook without a secret, Shoppex generates one and returns it in dynamic_webhook_secret in that create or update response. Store it immediately.

If the product has a signing secret, Shoppex signs ${deliveryId}.${timestamp}.${rawBody} and sends the digest in X-Shoppex-Signature-V2. Reject timestamps outside a 5-minute window.

Simple example:

import crypto from 'crypto';

function verifyShoppexSignature(
  rawBody: string,
  signatureHeader: string | undefined,
  deliveryId: string | undefined,
  timestampHeader: string | undefined,
) {
  if (!signatureHeader || !deliveryId || !timestampHeader) return false;
  const segments = signatureHeader.split(',').map((part) => part.trim());
  const parts = Object.fromEntries(segments.filter((part) => part.includes('=')).map((part) => {
    const [key, value] = part.trim().split('=');
    return [key, value ?? ''];
  }));
  if (!segments.includes('v1') || parts.t !== timestampHeader) return false;

  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) return false;
  if (!/^[0-9a-f]{64}$/i.test(parts.h ?? '')) return false;

  const expected = crypto
    .createHmac('sha256', process.env.SHOPPEX_DYNAMIC_WEBHOOK_SECRET!)
    .update(`${deliveryId}.${parts.t}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(parts.h, 'hex'), Buffer.from(expected, 'hex'));
}

X-Shoppex-Signature is retained as a legacy HMAC-SHA512 body-only header during migration. New dynamic delivery handlers should verify X-Shoppex-Signature-V2.

Recommended Deduplication Rule

Treat X-Shoppex-Idempotency-Key as the durable fulfillment key. Shoppex makes only one automatic request, but a merchant can explicitly retry a failed delivery. Your endpoint must return the same result for the same key instead of issuing a second token, license, or account.

Payload Shape

The payload contains both camelCase and snake_case for the most important fields. This is intentional so simple handlers do not need a translation layer first.

Top-Level Example

{
  "customerEmail": "[e-mail]",
  "customer_email": "[e-mail]",
  "productTitle": "Pro Pack",
  "product_title": "Pro Pack",
  "productType": "DYNAMIC",
  "product_type": "DYNAMIC",
  "quantity": 1,
  "variantId": "var_123",
  "variant_id": "var_123",
  "variantTitle": "Lifetime",
  "variant_title": "Lifetime",
  "customFields": {
    "discord_username": "tetra"
  },
  "custom_fields": {
    "discord_username": "tetra"
  },
  "invoice": {
    "id": "inv_db_123",
    "uniqid": "inv_123",
    "status": "COMPLETED",
    "type": "PRODUCT",
    "customer_email": "[e-mail]",
    "currency": "USD",
    "subtotal": "29.99",
    "discount": "0.00",
    "tax": "0.00",
    "total": "29.99",
    "country": "US",
    "custom_fields": {
      "discord_username": "tetra"
    },
    "created_at": "2026-03-24T13:00:00.000Z",
    "updated_at": "2026-03-24T13:01:00.000Z"
  },
  "product": {
    "id": "prod_db_123",
    "uniqid": "prod_123",
    "title": "Pro Pack",
    "type": "DYNAMIC",
    "subtype": null,
    "price": "29.99",
    "price_display": "29.99",
    "currency": "USD"
  },
  "shop": {
    "id": "shop_db_123",
    "name": "Example Shop"
  },
  "line_item": {
    "id": "line_item_123",
    "quantity": 1,
    "product_id": "prod_db_123",
    "product_title": "Pro Pack",
    "product_type": "DYNAMIC",
    "variant_id": "var_123",
    "variant_title": "Lifetime",
    "unit_price": "29.99",
    "total": "29.99",
    "custom_fields": {
      "discord_username": "tetra"
    },
    "addons": [],
    "metadata": {},
    "bundle_config": {}
  },
  "invoiceId": "inv_123",
  "invoice_id": "inv_123",
  "invoiceDbId": "inv_db_123",
  "invoice_db_id": "inv_db_123",
  "productId": "prod_db_123",
  "product_id": "prod_db_123",
  "shopId": "shop_db_123",
  "shop_id": "shop_db_123",
  "deliveryId": "dynamic:0d9e6f0a-1b2c-4d3e-8f90-a1b2c3d4e5f6:7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f:default:018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
  "delivery_id": "dynamic:0d9e6f0a-1b2c-4d3e-8f90-a1b2c3d4e5f6:7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f:default:018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
  "idempotencyKey": "dynamic:0d9e6f0a-1b2c-4d3e-8f90-a1b2c3d4e5f6:7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f:default:018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
  "idempotency_key": "dynamic:0d9e6f0a-1b2c-4d3e-8f90-a1b2c3d4e5f6:7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f:default:018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f"
}

Important Fields

Field	Type	Description
invoiceId / invoice_id	string	Public Shoppex invoice ID
invoiceDbId / invoice_db_id	string	Internal invoice row ID
productId / product_id	string	Internal product row ID
shopId / shop_id	string	Internal shop row ID
deliveryId / delivery_id	string	Stable delivery identifier
idempotencyKey / idempotency_key	string	Stable idempotency key
invoice	object	Invoice snapshot
product	object	Product snapshot
shop	object	Shop snapshot
line_item	object	Fulfilled line item snapshot

Response

Your endpoint should return 2xx and JSON.

Recommended response:

{
  "data": {
    "service_text": "Join the private server with the token below.",
    "dynamic_response": {
      "token": "dyn_123",
      "expires_at": "2026-12-31T23:59:59.000Z"
    },
    "deliveryType": "DYNAMIC",
    "count": 1
  }
}

What Shoppex Accepts

Shoppex accepts these response forms:

• A JSON object
• A JSON object with a nested data object
• A non-empty string

If you return a JSON object with data, Shoppex stores the nested data object.

{
  "data": {
    "service_text": "Use this token in the bot.",
    "dynamic_response": {
      "token": "dyn_123"
    }
  }
}

What Shoppex Stores

Shoppex normalizes your response into delivered items:

{
  "service_text": "Use this token in the bot.",
  "dynamic_response": {
    "token": "dyn_123"
  },
  "deliveryType": "DYNAMIC",
  "count": 1
}

If you return a plain string, Shoppex stores it as dynamic_response.

Acknowledge Asynchronous Fulfillment

If your system accepts the request but cannot return the delivery content within 15 seconds, respond with 200 and an explicit pending status. Shoppex then marks this line item as AWAITING_FULFILLMENT. Deliver the content later with POST /dev/v1/orders/{id}/items/{item_id}/fulfill.

The following example shows a complete callback exchange. The request body uses the same fields described above; the response is the asynchronous acknowledgement:

POST /shoppex/dynamic HTTP/1.1
Host: vendor.example.com
Content-Type: application/json
X-Shoppex-Idempotency-Key: dynamic:0d9e6f0a-1b2c-4d3e-8f90-a1b2c3d4e5f6:7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f:default:018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f
X-Shoppex-Delivery-Id: dynamic:0d9e6f0a-1b2c-4d3e-8f90-a1b2c3d4e5f6:7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f:default:018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f
X-Shoppex-Timestamp: 1785823200
X-Shoppex-Signature-V2: v1,t=1785823200,h=SIGNATURE_HEX

{
  "customerEmail": "[e-mail]",
  "customer_email": "[e-mail]",
  "productTitle": "Pro Pack",
  "product_title": "Pro Pack",
  "productType": "DYNAMIC",
  "product_type": "DYNAMIC",
  "quantity": 1,
  "variantId": "var_123",
  "variant_id": "var_123",
  "variantTitle": "Lifetime",
  "variant_title": "Lifetime",
  "customFields": { "discord_username": "tetra" },
  "custom_fields": { "discord_username": "tetra" },
  "invoice": {
    "id": "inv_db_123",
    "uniqid": "inv_123",
    "status": "COMPLETED",
    "type": "PRODUCT",
    "customer_email": "[e-mail]",
    "currency": "USD",
    "subtotal": "29.99",
    "discount": "0.00",
    "tax": "0.00",
    "total": "29.99",
    "country": "US",
    "custom_fields": { "discord_username": "tetra" },
    "created_at": "2026-08-04T08:39:00.000Z",
    "updated_at": "2026-08-04T08:40:00.000Z"
  },
  "product": {
    "id": "prod_db_123",
    "uniqid": "prod_123",
    "title": "Pro Pack",
    "type": "DYNAMIC",
    "subtype": null,
    "price": "29.99",
    "price_display": "29.99",
    "currency": "USD"
  },
  "shop": {
    "id": "shop_db_123",
    "name": "Example Shop"
  },
  "line_item": {
    "id": "line_item_123",
    "quantity": 1,
    "product_id": "prod_db_123",
    "product_title": "Pro Pack",
    "product_type": "DYNAMIC",
    "variant_id": "var_123",
    "variant_title": "Lifetime",
    "unit_price": "29.99",
    "total": "29.99",
    "custom_fields": { "discord_username": "tetra" },
    "addons": [],
    "metadata": {},
    "bundle_config": {}
  },
  "invoiceId": "inv_123",
  "invoice_id": "inv_123",
  "invoiceDbId": "inv_db_123",
  "invoice_db_id": "inv_db_123",
  "productId": "prod_db_123",
  "product_id": "prod_db_123",
  "shopId": "shop_db_123",
  "shop_id": "shop_db_123",
  "deliveryId": "dynamic:0d9e6f0a-1b2c-4d3e-8f90-a1b2c3d4e5f6:7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f:default:018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
  "delivery_id": "dynamic:0d9e6f0a-1b2c-4d3e-8f90-a1b2c3d4e5f6:7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f:default:018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
  "idempotencyKey": "dynamic:0d9e6f0a-1b2c-4d3e-8f90-a1b2c3d4e5f6:7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f:default:018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
  "idempotency_key": "dynamic:0d9e6f0a-1b2c-4d3e-8f90-a1b2c3d4e5f6:7c8d9e0f-1a2b-4c3d-8e9f-0a1b2c3d4e5f:default:018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f"
}

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

{
  "status": "pending"
}

The nested form is also accepted:

{
  "data": {
    "status": "pending"
  }
}

Pending must be explicit. An empty 2xx response keeps its historical meaning: Shoppex treats the line item as delivered and stores a placeholder delivery note. Never use an empty body to acknowledge asynchronous work.

Retry and Timeout Behavior

Shoppex makes one delivery attempt with a 15-second timeout. It does not retry automatically after a timeout, network error, 429, or 5xx response. This avoids duplicating a side effect when Shoppex cannot know whether your server provisioned the product before the connection failed.

After a terminal failure, Shoppex:

• marks the line item as FAILED
• notifies the merchant
• emits order:item.delivery_failed to subscribed merchant webhook endpoints

The merchant can fulfill the failed line item manually through the dashboard or the Developer API. The merchant can also explicitly retry the dynamic delivery, but the vendor may already have provisioned the product before the ambiguous failure. Deduplicate by X-Shoppex-Idempotency-Key before performing any side effect.

URL Requirements

Your dynamic_webhook must be a valid public http or https URL.

For local development, use a tunnel such as ngrok or Cloudflare Tunnel.

• https://dev.example.com/shoppex/dynamic — works
• https://abc123.ngrok.io/shoppex/dynamic — works for local testing
• http://127.0.0.1:3000/... — won’t work, Shoppex can’t reach private/loopback URLs

Example Handler

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json({
  verify: (req, _res, buf) => {
    (req as express.Request & { rawBody?: string }).rawBody = buf.toString('utf8');
  },
}));

const issuedTokens = new Map<string, { token: string; expires_at: string }>();

app.post('/shoppex/dynamic', async (req, res) => {
  const rawBody = (req as express.Request & { rawBody?: string }).rawBody ?? JSON.stringify(req.body);
  const signature = req.header('x-shoppex-signature-v2');
  const deliveryId = req.header('x-shoppex-delivery-id');
  const timestamp = req.header('x-shoppex-timestamp');
  if (!signature || !deliveryId || !timestamp) {
    return res.status(401).json({ error: 'Missing signature' });
  }
  const segments = signature.split(',').map((part) => part.trim());
  const parts = Object.fromEntries(segments.filter((part) => part.includes('=')).map((part) => {
    const [key, value] = part.trim().split('=');
    return [key, value ?? ''];
  }));
  if (
    !segments.includes('v1')
    || parts.t !== timestamp
    || Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300
    || !/^[0-9a-f]{64}$/i.test(parts.h ?? '')
  ) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  const expectedSignature = crypto
    .createHmac('sha256', process.env.SHOPPEX_DYNAMIC_WEBHOOK_SECRET!)
    .update(`${deliveryId}.${timestamp}.${rawBody}`)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(parts.h, 'hex'), Buffer.from(expectedSignature, 'hex'))) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const idempotencyKey = String(
    req.header('x-shoppex-idempotency-key')
      ?? req.body.idempotencyKey
      ?? req.body.idempotency_key
      ?? ''
  ).trim();

  if (!idempotencyKey) {
    return res.status(400).json({ error: 'Missing idempotency key' });
  }

  let existing = issuedTokens.get(idempotencyKey);

  if (!existing) {
    existing = {
      token: `dyn_${Math.random().toString(36).slice(2, 10)}`,
      expires_at: '2026-12-31T23:59:59.000Z',
    };

    issuedTokens.set(idempotencyKey, existing);
  }

  return res.json({
    data: {
      service_text: 'Use this token in the bot.',
      dynamic_response: existing,
      deliveryType: 'DYNAMIC',
      count: 1,
    },
  });
});

Recommended Pattern

Here’s what a solid integration looks like:

• use idempotencyKey as your fulfillment key
• return the same result if a merchant explicitly retries a failed delivery
• keep the response short and structured
• put the customer-facing text in service_text
• put machine-readable output like tokens or credentials in dynamic_response

Avoid:

• generating a new token when the same idempotency key is received again
• depending on field names from only one casing style
• returning HTML or large non-JSON payloads

---

Next Steps

Webhooks Overview

Setup, signatures, and retry policies

Webhook Events

Full event type reference and payload schemas