Webhook Setup

This guide walks you through setting up webhooks in your Quickbutik store and configuring your application to receive and process webhook events reliably.

Configuration in Quickbutik

Access webhook settings

Log into your Quickbutik Control Panel and navigate to Settings → Webhooks

Add webhook URL

Enter your webhook endpoint URL where you want to receive notifications:

https://your-domain.com/webhooks/quickbutik

Your webhook URL must be publicly accessible and respond to GET requests. Use HTTPS in production for security.

Select events

Choose which events should trigger webhook notifications:

Order events: order.new, order.done, order.cancelled
Product events: product.add, product.update, product.delete

Turn on the secret key (recommended)

Tick Use secret key? and save. Quickbutik creates a secret key for the webhook and sends it with every request as the securityhash query parameter. Open the webhook again to see the value, shown as securityhash=<your key>. See Verifying requests.

Test your webhook

There is no test button in the Control Panel. Trigger a real event instead, for example by saving a product when the webhook listens to product.update, and check that your endpoint receives the request. Events are sent once a minute, so allow a minute or two.

Verifying requests

Each webhook can have its own secret key. When Use secret key? is ticked on a webhook, Quickbutik adds the key, unchanged, to every request it sends to that webhook’s URLs as the securityhash query parameter:

GET /webhooks/quickbutik?id=987654&order_id=12345&event_type=order.new&securityhash=4823019576

securityhash is not calculated per request. It is not a signature or an HMAC of the request, and there is no algorithm to reproduce. It is a fixed shared secret: the same value is sent with every request to that webhook for as long as the key exists.

To verify that a request comes from your store:

Open the webhook in your Quickbutik Control Panel and copy the value after securityhash=.
Store it on your side as a secret, for example in an environment variable.
Compare the securityhash parameter of each incoming request with the stored value. If the parameter is missing or does not match, ignore the request.
Fetch the order or product through the API with the ID from the request. The request only carries the event type and an ID, so the data you act on always comes straight from Quickbutik.

Treat the key as an opaque string and compare it in constant time. Do not assume a fixed length or format.

const crypto = require('crypto');

const WEBHOOK_SECRET = process.env.QUICKBUTIK_WEBHOOK_SECRET;

function isFromQuickbutik(req) {
  const received = req.query.securityhash;

  if (typeof received !== 'string' || !received || !WEBHOOK_SECRET) {
    return false;
  }

  const a = Buffer.from(received);
  const b = Buffer.from(WEBHOOK_SECRET);

  // Constant-time comparison, so the key can't be guessed from response times
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.get('/webhooks/quickbutik', (req, res) => {
  if (!isFromQuickbutik(req)) {
    return res.status(401).send('Unauthorized');
  }

  res.status(200).send('OK');

  const { event_type, order_id, product_id } = req.query;
  processWebhook(event_type, { order_id, product_id });
});

import hmac
import os

from flask import Flask, request

app = Flask(__name__)
WEBHOOK_SECRET = os.environ.get('QUICKBUTIK_WEBHOOK_SECRET', '')

def is_from_quickbutik(req):
    received = req.args.get('securityhash', '')

    if not received or not WEBHOOK_SECRET:
        return False

    # Constant-time comparison, so the key can't be guessed from response times
    return hmac.compare_digest(received.encode(), WEBHOOK_SECRET.encode())

@app.route('/webhooks/quickbutik', methods=['GET'])
def quickbutik_webhook():
    if not is_from_quickbutik(request):
        return 'Unauthorized', 401

    event_type = request.args.get('event_type')
    order_id = request.args.get('order_id')
    product_id = request.args.get('product_id')

    # Fetch the order or product through the API and process it
    process_webhook(event_type, order_id, product_id)

    return 'OK', 200

Managing the key

The key stays the same when you edit the webhook.
Untick Use secret key? and save to remove the key. Requests to that webhook are then sent without securityhash.
Tick it again and save to create a new key. The old key is no longer sent, so update the stored value on your side straight away.
Each webhook has its own key. If several webhooks send to the same endpoint, accept the key of each one.

The key is part of the request URL, so it can end up in the access logs of your web server, load balancer or proxy. Use HTTPS, keep those logs private, and create a new key if you think it has leaked.

Development Setup

For local development, use a tool like ngrok to expose your local server:

# Install ngrok
npm install -g ngrok

# Start your local webhook server
node webhook-server.js

# In another terminal, expose your local server
ngrok http 3000

# Copy the ngrok URL to your Quickbutik webhook settings
# Example: https://abc123.ngrok.io/webhooks/quickbutik

const express = require('express');
const app = express();

app.get('/webhooks/quickbutik', (req, res) => {
  console.log('Webhook received:', {
    event_type: req.query.event_type,
    order_id: req.query.order_id,
    product_id: req.query.product_id,
    timestamp: new Date().toISOString(),
    ip: req.ip,
    headers: req.headers
  });
  
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Production Deployment

For production environments, ensure your webhook endpoint is robust and scalable:

const express = require('express');
const rateLimit = require('express-rate-limit');
const helmet = require('helmet');

const app = express();

// Security middleware
app.use(helmet());

// Rate limiting
const webhookLimiter = rateLimit({
  windowMs: 1 * 60 * 1000, // 1 minute
  max: 100, // limit each IP to 100 requests per windowMs
  message: 'Too many webhook requests from this IP',
  standardHeaders: true,
  legacyHeaders: false,
});

app.use('/webhooks', webhookLimiter);

// Health check endpoint
app.get('/health', (req, res) => {
  res.status(200).json({
    status: 'healthy',
    timestamp: new Date().toISOString()
  });
});

// Webhook endpoint
app.get('/webhooks/quickbutik', async (req, res) => {
  const { event_type, order_id, product_id } = req.query;
  
  // Log webhook receipt
  console.log(`Webhook received: ${event_type}`, {
    order_id,
    product_id,
    timestamp: new Date().toISOString(),
    ip: req.ip
  });
  
  // Respond immediately
  res.status(200).send('OK');
  
  try {
    // Add to processing queue
    await addToQueue({
      event_type,
      order_id,
      product_id,
      received_at: new Date().toISOString()
    });
  } catch (error) {
    console.error('Failed to queue webhook:', error);
    
    // Send alert but don't fail the webhook response
    await sendAlert({
      type: 'webhook_queue_error',
      event_type,
      error: error.message
    });
  }
});

async function addToQueue(webhookData) {
  // Add to Redis queue, SQS, or your preferred queue system
  // This ensures webhook processing doesn't block the response
  
  if (process.env.REDIS_URL) {
    const redis = require('redis');
    const client = redis.createClient({ url: process.env.REDIS_URL });
    await client.lPush('webhook_queue', JSON.stringify(webhookData));
  }
}

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook server running on port ${PORT}`);
});

FROM node:18-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy application
COPY . .

# Create non-root user
RUN addgroup -g 1001 -S webhook
RUN adduser -S webhook -u 1001

# Security
RUN chown -R webhook:webhook /app
USER webhook

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

EXPOSE 3000

CMD ["node", "webhook-server.js"]

Troubleshooting

Common Issues

Webhook not receiving events

Possible causes:

Webhook URL is not publicly accessible
Firewall blocking incoming requests
Server not running or crashed
Wrong endpoint path configured
The webhook is not active (Activate Webhook is not ticked) or does not listen to the event

Solutions:

Test your endpoint with curl: curl "https://your-domain.com/webhooks/quickbutik?event_type=test"
Check server logs for errors
Verify webhook URL and events in Quickbutik settings
Wait a minute or two, since events are sent once a minute
Use tools like ngrok for local testing

Getting timeout errors

Quickbutik closes each request after 10 seconds and does not send it again.Possible causes:

Webhook handler takes too long to respond
Processing heavy operations synchronously
Database or external API calls blocking response

Solutions:

Always respond with 200 OK immediately
Process webhook data asynchronously
Use queue systems for heavy processing
Implement timeout handling

Receiving duplicate events

Possible causes:

The same endpoint URL is added to more than one webhook, or more than once in the same webhook. Each one gets its own request.
The same change was made more than once in the store, which creates a new event each time

Solutions:

Add each endpoint URL to only one webhook, and only once
Implement idempotent processing
Use the id parameter to skip an event you have already processed
Use database transactions for atomic operations

Missing webhook events

Quickbutik sends each event once and does not retry. A request that your endpoint did not receive, or did not answer within 10 seconds, is lost.Possible causes:

Endpoint was down during event
Endpoint did not answer within 10 seconds
Your own rate limiting or firewall rejected the request
The webhook is not active or does not listen to the event

Solutions:

Monitor webhook endpoint uptime
Respond quickly and process the event asynchronously
Queue received events, so a processing error on your side does not lose them
Regularly poll API for missed events as backup

Next Steps

Event Types

Explore all available webhook events and their data

Getting Started

Guides

Settings

Webhooks

Settings

Scripts

Orders

Products

Categories

Payment Methods

Shipping Methods

Metadata

Configuration in Quickbutik

Verifying requests

Managing the key

Development Setup

Production Deployment

Troubleshooting

Common Issues

Next Steps

Event Types

​Configuration in Quickbutik

​Verifying requests

​Managing the key

​Development Setup

​Production Deployment

​Troubleshooting

​Common Issues

​Next Steps

Event Types

Configuration in Quickbutik

Verifying requests

Managing the key

Development Setup

Production Deployment

Troubleshooting

Common Issues

Next Steps