Webhooks

Webhooks allow your application to receive real-time notifications when important events happen in your Quickbutik store. Instead of constantly polling the API, webhooks notify your application when events occur, usually within a minute.

Common use cases:

Sync new orders to your fulfillment system
Update inventory levels across multiple platforms
Send custom order confirmations or notifications
Trigger automated workflows and integrations

How Webhooks Work

When an event occurs in your store (like a new order), Quickbutik sends an HTTP GET request to your configured webhook URL with event details as query parameters.

Quick Setup

Create webhook endpoint

Set up an endpoint in your application to receive webhook notifications

app.get('/webhooks/quickbutik', (req, res) => {
  const { event_type, order_id, product_id } = req.query;
  
  // Always respond quickly
  res.status(200).send('OK');
  
  // Process webhook asynchronously
  processWebhook(event_type, { order_id, product_id });
});

Configure in Quickbutik

Enable webhooks in your Quickbutik Control Panel under Settings → Webhooks and add your endpoint URL

Handle events

Process the webhook events in your application based on the event type

Event Structure

All webhook requests are sent as GET requests with the following query parameters:

Parameter	Description	Example
`event_type`	The type of event that occurred	`order.new`, `product.update`
`order_id`	Order ID (for order events)	`12345`
`product_id`	Product ID (for product events)	`67890`
`id`	Unique ID of the event, the same for every URL the event is sent to. Not sent when your webhook URL already contains a query string	`987654`
`securityhash`	The webhook’s secret key. Only sent when Use secret key? is ticked on the webhook. See Verifying requests	`4823019576`

If your webhook URL already contains a query string, its own parameters are kept, and all of the parameters above except id are added to them.

Example Webhook Request

GET /your-webhook-endpoint?id=987654&order_id=12345&event_type=order.new&securityhash=4823019576
Host: your-domain.com

Delivery

A job sends new events once a minute, oldest first, so a request usually arrives within a minute of the event. When many events are queued it can take longer.
Each event is sent once to every URL of every active webhook that listens to it.
Quickbutik waits at most 10 seconds for your endpoint and does not look at the response. A request that fails or times out is not retried.

Complete Example

Here’s a complete webhook handler that processes different event types:

const express = require('express');
const QuickbutikAPI = require('./quickbutik-api');

const app = express();
const api = new QuickbutikAPI(process.env.QUICKBUTIK_API_KEY);

app.get('/webhooks/quickbutik', async (req, res) => {
  const { event_type, order_id, product_id } = req.query;
  
  console.log(`Received webhook: ${event_type}`, { order_id, product_id });
  
  // Acknowledge webhook immediately (important!)
  res.status(200).send('OK');
  
  try {
    // Process webhook asynchronously
    switch (event_type) {
      case 'order.new':
        await handleNewOrder(order_id);
        break;
      case 'order.done':
        await handleOrderShipped(order_id);
        break;
      case 'order.cancelled':
        await handleOrderCancelled(order_id);
        break;
      case 'product.add':
        await handleProductAdded(product_id);
        break;
      case 'product.update':
        await handleProductUpdated(product_id);
        break;
      case 'product.delete':
        await handleProductDeleted(product_id);
        break;
      default:
        console.log(`Unhandled event type: ${event_type}`);
    }
  } catch (error) {
    console.error(`Error processing webhook ${event_type}:`, error);
    
    // In production, add to retry queue or send alert
    await handleWebhookError(event_type, { order_id, product_id }, error);
  }
});

async function handleNewOrder(orderId) {
  console.log(`Processing new order: ${orderId}`);
  
  // Fetch complete order details
  const orders = await api.getOrders({ 
    order_id: orderId,
    include_details: true 
  });
  
  if (orders && orders.length > 0) {
    const order = orders[0];
    
    // Your business logic here
    await processNewOrder(order);
    console.log(`Successfully processed order ${orderId}`);
  }
}

async function handleProductUpdated(productId) {
  console.log(`Processing product update: ${productId}`);
  
  // Fetch updated product details
  const products = await api.getProducts({ 
    product_id: productId,
    include_details: true 
  });
  
  if (products && products.length > 0) {
    const product = products[0];
    
    // Your business logic here
    await syncProductToExternalSystem(product);
    console.log(`Successfully synced product ${productId}`);
  }
}

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

from flask import Flask, request, jsonify
import asyncio
import logging
from quickbutik_api import QuickbutikAPI

app = Flask(__name__)
logging.basicConfig(level=logging.INFO)

api = QuickbutikAPI(os.getenv('QUICKBUTIK_API_KEY'))

@app.route('/webhooks/quickbutik', methods=['GET'])
def quickbutik_webhook():
    event_type = request.args.get('event_type')
    order_id = request.args.get('order_id')
    product_id = request.args.get('product_id')
    
    app.logger.info(f'Received webhook: {event_type}, order_id: {order_id}, product_id: {product_id}')
    
    # Acknowledge webhook immediately (important!)
    response = jsonify({'status': 'received'})
    
    # Process webhook asynchronously
    try:
        if event_type == 'order.new':
            asyncio.create_task(handle_new_order(order_id))
        elif event_type == 'order.done':
            asyncio.create_task(handle_order_shipped(order_id))
        elif event_type == 'order.cancelled':
            asyncio.create_task(handle_order_cancelled(order_id))
        elif event_type == 'product.add':
            asyncio.create_task(handle_product_added(product_id))
        elif event_type == 'product.update':
            asyncio.create_task(handle_product_updated(product_id))
        elif event_type == 'product.delete':
            asyncio.create_task(handle_product_deleted(product_id))
        else:
            app.logger.info(f'Unhandled event type: {event_type}')
    except Exception as error:
        app.logger.error(f'Error processing webhook {event_type}: {error}')
        asyncio.create_task(handle_webhook_error(event_type, {'order_id': order_id, 'product_id': product_id}, error))
    
    return response, 200

async def handle_new_order(order_id):
    app.logger.info(f'Processing new order: {order_id}')
    
    try:
        # Fetch complete order details
        orders = await api.get_orders(order_id=order_id, include_details=True)
        
        if orders:
            order = orders[0]
            
            # Your business logic here
            await process_new_order(order)
            app.logger.info(f'Successfully processed order {order_id}')
    except Exception as error:
        app.logger.error(f'Failed to process order {order_id}: {error}')

async def handle_product_updated(product_id):
    app.logger.info(f'Processing product update: {product_id}')
    
    try:
        # Fetch updated product details
        products = await api.get_products(product_id=product_id, include_details=True)
        
        if products:
            product = products[0]
            
            # Your business logic here
            await sync_product_to_external_system(product)
            app.logger.info(f'Successfully synced product {product_id}')
    except Exception as error:
        app.logger.error(f'Failed to sync product {product_id}: {error}')

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

Best Practices

Respond Quickly

Respond within 10 seconds. Quickbutik closes the request after 10 seconds. Process the actual work asynchronously.

No Retries

Failed requests are not sent again. If your endpoint is down or too slow, the event is lost. Poll the API as a backup for critical data.

Validate Events

Check the securityhash parameter on every request to make sure it comes from your store.

Error Handling

Implement proper error handling and retry mechanisms for failed webhook processing.

Important Considerations:

Webhooks are sent as GET requests (not POST)
Failed or timed-out requests are not retried
The same event can occasionally arrive more than once, so make your processing idempotent
Use the API to fetch complete data when processing webhooks

Testing Webhooks

Use tools like ngrok to test webhooks locally:

# Install ngrok
npm install -g ngrok

# Start your webhook server
node webhook-server.js

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

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

// Simple webhook tester
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()
  });
  
  res.status(200).send('Webhook received successfully');
});

app.listen(3000, () => {
  console.log('Webhook test server running on http://localhost:3000');
  console.log('Test URL: http://localhost:3000/webhooks/quickbutik');
});

Getting Started

Guides

Settings

Settings

Scripts

Orders

Products

Categories

Payment Methods

Shipping Methods

Metadata

Webhooks

How Webhooks Work

Quick Setup

Event Structure

Example Webhook Request

Delivery

Complete Example

Best Practices

Respond Quickly

No Retries

Validate Events

Error Handling

Testing Webhooks

Next Steps

Event Types

Setup Guide

​How Webhooks Work

​Quick Setup

​Event Structure

​Example Webhook Request

​Delivery

​Complete Example

​Best Practices

Respond Quickly

No Retries

Validate Events

Error Handling

​Testing Webhooks

​Next Steps

Event Types

Setup Guide

How Webhooks Work

Quick Setup

Event Structure

Example Webhook Request

Delivery

Complete Example

Best Practices

Testing Webhooks

Next Steps