Custom Webhooks - Quickei Developer Docs

Build custom integrations with any system by receiving real-time webhook notifications for payment events.

Overview

Whenever a payment event occurs (paid, expired, cancelled, refunded), Quickei sends an HTTP POST request to your configured callback_url with a JSON payload. The request includes an HMAC-SHA256 signature for verification.

Webhook Flow

Events

Event	Trigger
`pos.order.paid`	Customer completed payment
`pos.order.expired`	Order expired before payment
`pos.order.cancelled`	Order cancelled by merchant
`pos.order.refunded`	Payment refunded to customer

Payload Format

{
  "event": "pos.order.paid",
  "timestamp": "2026-03-15T14:02:30+00:00",
  "data": {
    "order_id": "POS-20260315-A1B2C3",
    "amount": 25.00,
    "currency": "EUR",
    "status": "PAID",
    "reference": "INV-2026-001",
    "terminal_id": "terminal-01",
    "trx_id": "TRX-98765",
    "paid_at": "2026-03-15T14:02:30+00:00"
  }
}

Headers

Header	Description
`Content-Type`	`application/json`
`X-Quickei-Event`	Event name (e.g. `pos.order.paid`)
`X-Quickei-Signature`	HMAC-SHA256 signature of the request body

Signature Verification

Every webhook includes an X-Quickei-Signature header. Always verify the signature before processing the event.

PHP
Python
Node.js

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_QUICKEI_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac(
    'sha256',
    $payload,
    $client_secret  // Your API client secret
);

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Invalid signature');
}

// Signature valid — process the event
$event = json_decode($payload, true);

switch ($event['event']) {
    case 'pos.order.paid':
        // Update order, send confirmation email, etc.
        break;
    case 'pos.order.refunded':
        // Process refund in your system
        break;
}

http_response_code(200);

import hmac
import hashlib
import json

def handle_webhook(request):
    payload = request.body
    signature = request.headers.get('X-Quickei-Signature', '')

    expected = 'sha256=' + hmac.new(
        client_secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return HttpResponse(status=403)

    event = json.loads(payload)

    if event['event'] == 'pos.order.paid':
        # Update order in your system
        pass

    return HttpResponse(status=200)

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  const payload = JSON.stringify(req.body);
  const signature = req.headers['x-quickei-signature'] || '';

  const expected = 'sha256=' + crypto
    .createHmac('sha256', clientSecret)
    .update(payload)
    .digest('hex');

  if (signature !== expected) {
    return res.status(403).send('Invalid signature');
  }

  // Signature valid — process the event
  const { event, data } = req.body;

  if (event === 'pos.order.paid') {
    // Update order in your system
  }

  res.sendStatus(200);
});

Retry Policy

If your endpoint does not return a 200 status code, Quickei retries with exponential backoff:

Attempt	Delay	Total Wait
1st retry	10 seconds	10s
2nd retry	60 seconds	1m 10s
3rd retry	300 seconds	6m 10s

After 3 failed attempts, the webhook is marked as failed. Check the API Logs in your Merchant Dashboard for delivery status.

Best Practices

Always verify signatures

Never process a webhook without verifying the X-Quickei-Signature header. This prevents spoofed events.

Return 200 quickly

Acknowledge the webhook immediately with a 200 response. Do heavy processing (email, inventory, etc.) asynchronously.

Handle duplicates

Webhooks may be delivered more than once. Use the order_id as an idempotency key to prevent double-processing.

Use HTTPS only

Webhook URLs must use HTTPS. HTTP endpoints and private/localhost IPs are rejected.

Callback URLs pointing to localhost, 127.0.0.1, or private IP ranges (10.x, 172.16-31.x, 192.168.x) are blocked for security.

​Overview

​Webhook Flow

​Events

​Payload Format

​Headers

​Signature Verification

​Retry Policy

​Best Practices

Always verify signatures

Return 200 quickly

Handle duplicates

Use HTTPS only

Overview

Webhook Flow

Events

Payload Format

Headers

Signature Verification

Retry Policy

Best Practices