Skip to main content

Documentation Index

Fetch the complete documentation index at: https://quickbutik.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

1

Access webhook settings

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

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.
3

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
4

Test your webhook

Use the test function in the Quickbutik panel to verify your endpoint is working correctly

​
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

​
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}`);
});

​
Troubleshooting

​
Common Issues

Possible causes:
  • Webhook URL is not publicly accessible
  • Firewall blocking incoming requests
  • Server not running or crashed
  • Wrong endpoint path configured
Solutions:
  • Test your endpoint with curl: curl "https://your-domain.com/webhooks/quickbutik?event_type=test"
  • Check server logs for errors
  • Verify webhook URL in Quickbutik settings
  • Use tools like ngrok for local testing
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
Possible causes:
  • Webhook endpoint responding slowly or with errors
  • Network issues causing retries
  • Processing failures triggering redelivery
Solutions:
  • Implement idempotent processing
  • Store processed webhook IDs to prevent duplicates
  • Respond quickly with 200 OK
  • Use database transactions for atomic operations
Possible causes:
  • Endpoint was down during event
  • Processing errors causing webhook to be marked as failed
  • Rate limiting rejecting webhooks
Solutions:
  • Implement reliable webhook processing with retries
  • Monitor webhook endpoint uptime
  • Use dead letter queues for failed webhooks
  • Regularly poll API for missed events as backup

​
Next Steps

Event Types

Explore all available webhook events and their data