Skip to main content
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