Dynamic product delivery

dynamic_webhook is a direct server-to-server callback that Shoppex sends when a DYNAMIC product needs fulfillment after a paid order, separate from normal event webhooks.

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

How it works

You create a product with type: "DYNAMIC", set dynamic_webhook, and keep the generated dynamic webhook signing secret.
A customer pays for that product.
Shoppex sends POST to your dynamic_webhook URL.
Your server returns delivery data, or clearly states that it will fulfill the line item later.
Shoppex either stores the delivered content or marks the line item as AWAITING_FULFILLMENT.

Webhook request

HTTP details

Shoppex sends a POST request with Content-Type: application/json and a JSON body that contains invoice, product, shop, and line item data. Your dynamic_webhook URL must be a public http or https address. 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/... — does not work. Shoppex cannot reach private or loopback URLs

Example body

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

{
  "customerEmail": "[email protected]",
  "customer_email": "[email protected]",
  "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": "[email protected]",
    "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"
}

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

Request 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`

Signature verification

Dynamic product delivery has its own signing secret on the product. This secret is separate from normal Shoppex event webhook secrets: normal webhooks use the endpoint secret from Settings → Webhooks, dynamic delivery uses the product’s dynamic_webhook_secret. When you create or update 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 once as dynamic_webhook_secret in that create or update response. Store it immediately. If the product has a signing secret, Shoppex signs ${deliveryId}.${timestamp}.${rawBody} with HMAC-SHA256 and sends the digest in X-Shoppex-Signature-V2. Reject timestamps outside a 5-minute window.

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'));
}

Shoppex keeps X-Shoppex-Signature as a legacy HMAC-SHA512 body-only header during the migration period. New dynamic delivery handlers must verify X-Shoppex-Signature-V2.

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

Webhook response

Success

Your endpoint must return 2xx status 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
  }
}

A solid integration follows this pattern:

Use idempotencyKey as your fulfillment key.
Return the same result if a merchant 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 the following:

Generating a new token when Shoppex sends the same idempotency key again.
Depending on field names from only one casing style.
Returning HTML or a large non-JSON payload.

Shoppex accepts three response forms: a JSON object, a JSON object with a nested data object, or 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"
    }
  }
}

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. If your system accepts the request but cannot return the delivery content within 15 seconds, respond with 200 and a clear 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": "[email protected]",
  "customer_email": "[email protected]",
  "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": "[email protected]",
    "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"
  }
}

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,
    },
  });
});

Retryable errors

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 already delivered the product before the connection failed. After this terminal failure, Shoppex:

marks the line item as FAILED
notifies the merchant
sends 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, or retry the dynamic delivery again. A timeout or network error does not tell you whether the vendor already delivered the product. Check X-Shoppex-Idempotency-Key for duplicates before you take any action with a side effect.

Non-retryable errors

You must state pending clearly. 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 say that you will deliver the content later.

An empty or accidentally empty 2xx response has no retry path. Shoppex already considers the item delivered, so it does not call your endpoint again for that line item. Always send the pending response shown above when you cannot deliver content immediately.

Invoice status behavior

Shoppex calls the dynamic_webhook URL during product fulfillment, after the invoice reaches a paid or completed state. A 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.

Endpoint outcome	Line item status
Returns delivery content (`2xx`)	Delivered — Shoppex stores your response
Returns a clear pending status (`2xx`)	`AWAITING_FULFILLMENT` until you call the fulfill endpoint
Times out, errors, or returns a non-`2xx` status	`FAILED` — Shoppex notifies the merchant and sends `order:item.delivery_failed`
Returns an empty `2xx` body	Delivered, with a placeholder delivery note

Webhooks

Setup, signatures, and retry policies

Webhook events

Full event type reference and payload schemas

Start here

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Integrations

Resellers

Email marketing

Tutorials

Dynamic product delivery

How it works

Webhook request

HTTP details

Example body

Request headers

Signature verification

Webhook response

Success

Example handler

Retryable errors

Non-retryable errors

Invoice status behavior

Webhooks

Webhook events

​How it works

​Webhook request

​HTTP details

​Example body

​Request headers

​Signature verification

​Webhook response

​Success

​Example handler

​Retryable errors

​Non-retryable errors

​Invoice status behavior

Webhooks

Webhook events

How it works

Webhook request

HTTP details

Example body

Request headers

Signature verification

Webhook response

Success

Example handler

Retryable errors

Non-retryable errors

Invoice status behavior