Webhooks-API

Webhooks ermöglichen es Ihrer Anwendung, Echtzeit-HTTP-Benachrichtigungen zu erhalten, wenn Ereignisse in Ihrem Mercozy-Shop auftreten. Anstatt die API abzufragen, registrieren Sie eine URL und Mercozy sendet die Ereignisdaten automatisch per POST.

Schnellstart

In 3 Schritten starten:

curl -X POST "https://api.mercozy.com/api/v1/external/webhooks" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My ERP Integration",
    "url": "https://your-app.com/webhooks/mercozy",
    "events": ["order.created", "order.cancelled", "payment.received"]
  }'

app.post('/webhooks/mercozy', (req, res) => {
  // 1. Verify signature (see below)
  const signature = req.headers['x-webhook-signature'];
  if (!verifySignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // 2. Process the event
  const { type, data } = req.body;
  switch (type) {
    case 'order.created':
      syncOrderToERP(data);
      break;
    case 'payment.received':
      updateAccountingSystem(data);
      break;
  }

  // 3. Respond quickly with 200
  res.status(200).json({ received: true });
});

curl -X POST "https://api.mercozy.com/api/v1/external/webhooks/{id}/test" \
  -H "X-API-Key: mk_live_your_key_here"

Endpunkte

Feldreferenz

Verfuegbare Ereignistypen

Mercozy unterstützt 18 Webhook-Ereignistypen in 6 Kategorien. Abonnieren Sie nur die Ereignisse, die Sie benötigen.

Webhook-Payload

Jede Webhook-Zustellung enthaelt den Ereignistyp, Zeitstempel und die relevanten Ressourcendaten.

Bestellereignis-Daten

{
  "id": "evt_clx1abc2def3",
  "type": "order.created",
  "timestamp": "2026-03-19T10:30:00Z",
  "data": {
    "id": "clx9order123",
    "orderNumber": "ORD-1042",
    "status": "PENDING",
    "total": 4999,
    "currency": "USD"
  }
}

Zahlungsereignis-Daten

{
  "id": "evt_clx2pay4ghi5",
  "type": "payment.received",
  "timestamp": "2026-03-19T10:35:00Z",
  "data": {
    "orderId": "clx9order123",
    "orderNumber": "ORD-1042",
    "amount": 4999,
    "currency": "USD",
    "paymentMethod": "CARD",
    "status": "CAPTURED"
  }
}

Produktereignis-Daten

{
  "id": "evt_clx3prod6jkl",
  "type": "product.created",
  "timestamp": "2026-03-19T11:00:00Z",
  "data": {
    "id": "clx9prod789",
    "name": "Organic Coffee Beans",
    "sku": "COF-001",
    "price": 1299,
    "status": "ACTIVE"
  }
}

Lieferereignis-Daten

{
  "id": "evt_clx4del7mno",
  "type": "delivery.completed",
  "timestamp": "2026-03-19T14:22:00Z",
  "data": {
    "orderId": "clx9order123",
    "orderNumber": "ORD-1042"
  }
}

HTTP-Header

Jede Webhook-Anfrage enthält die folgenden Header:

Signaturverifizierung

Jeder Webhook enthält einen X-Webhook-Signature-Header mit einer HMAC-SHA256-Signatur. Überprüfen Sie diese Signatur immer, bevor Sie das Ereignis verarbeiten, um sicherzustellen, dass die Anfrage von Mercozy stammt.

Node.js

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, timestamp, secret) {
  // Signature is computed over "timestamp.body"
  const message = timestamp + '.' + rawBody;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express middleware
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-webhook-signature'];
  const ts = req.headers['x-webhook-timestamp'];
  if (!verifyWebhook(req.body, sig, ts, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  // Process event...
  res.status(200).json({ received: true });
});

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, timestamp: str, secret: str) -> bool:
    # Signature is computed over "timestamp.body"
    message = (timestamp + '.').encode() + payload
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        message,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# Flask example
@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    sig = request.headers.get('X-Webhook-Signature')
    ts = request.headers.get('X-Webhook-Timestamp')
    if not verify_webhook(request.data, sig, ts, WEBHOOK_SECRET):
        return 'Invalid signature', 401
    event = request.get_json()
    # Process event...
    return {'received': True}, 200

<?php
function verifyWebhook(string $payload, string $signature, string $timestamp, string $secret): bool {
    // Signature is computed over "timestamp.body"
    $message = $timestamp . '.' . $payload;
    $expected = 'sha256=' . hash_hmac('sha256', $message, $secret);
    return hash_equals($expected, $signature);
}

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_WEBHOOK_TIMESTAMP'] ?? '';
if (!verifyWebhook($payload, $signature, $timestamp, $webhookSecret)) {
    http_response_code(401);
    exit('Invalid signature');
}
$event = json_decode($payload, true);
// Process event...
http_response_code(200);
echo json_encode(['received' => true]);

Wiederholungsrichtlinie

Wenn Ihr Endpoint einen Nicht-2xx-Statuscode zurückgibt oder das Zeitlimit überschreitet (10 Sekunden), wird Mercozy die Zustellung mit exponentiellem Backoff erneut versuchen:

Nach 3 fehlgeschlagenen Versuchen wird die Zustellung als fehlgeschlagen markiert. Sie können fehlgeschlagene Zustellungen manuell über das Dashboard oder die API erneut versuchen.

Best Practices

• Innerhalb von 5 Sekunden antworten — Geben Sie sofort einen 200-Status zurück und verarbeiten Sie das Ereignis asynchron. Das Zeitlimit von Mercozy beträgt 10 Sekunden.

• Signaturen immer verifizieren — Überprüfen Sie den X-Webhook-Signature-Header, bevor Sie ein Ereignis verarbeiten, um gefälschte Anfragen zu verhindern.

• Duplikate behandeln (Idempotenz) — Verwenden Sie den X-Webhook-ID-Header zur Deduplizierung. Speichern Sie verarbeitete Ereignis-IDs und überspringen Sie bereits behandelte.

• HTTPS-Endpoints verwenden — Mercozy erfordert HTTPS-URLs in der Produktion, um Webhook-Daten während der Übertragung zu schützen.

• Protokollieren und überwachen — Protokollieren Sie alle eingehenden Webhooks und überwachen Sie Fehler. Verwenden Sie die Zustellprotokoll-API, um den Zustellstatus zu überprüfen.