Zum Inhalt springen

Webhooks

Wissen, wann sich Geld bewegt

Echtzeit-Benachrichtigungen zu Einzahlungen, Auszahlungen, virtuellen Konten, Abonnements, Devisentausch, Wire In und Wire Out – jede mit HMAC-SHA256 signiert, damit Sie jeden Request prüfen können, bevor Sie handeln.

  • HMAC-SHA256-Signaturen
  • Wiederholungen mit Backoff
  • Nach Land und Konto gefiltert

Konfiguration

Benachrichtigungen im Business Portal einrichten

Für die Registrierung eines Endpunkts ist kein Code nötig. Jeder Eintrag lässt sich nach Land und Konto eingrenzen.

  1. 01

    Benachrichtigungen öffnen

    Gehen Sie im Business Portal zu Configurations → Clients → Notifications.

  2. 02

    HTTPS-URL hinzufügen

    Registrieren Sie den öffentlichen HTTPS-Endpunkt auf Ihren Servern, der die Events empfängt.

  3. 03

    Eintrag eingrenzen

    Wählen Sie ein Land oder All sowie das Konto, zu dem die Benachrichtigungen gehören.

  4. 04

    Header ergänzen und testen

    Fügen Sie optional eigene Header für Ihr Gateway hinzu und führen Sie dann eine Testtransaktion auf Stage aus.

Payload

Ein Umschlag für alle Events

Alle Benachrichtigungen teilen dieselben Root-Felder, sodass ein einziger Handler sie alle routen kann. Der Body ist JSON und wird mit Content-Type text/plain zugestellt.

  • transactionType: PayIn, PayOut, VirtualAccount, Subscription, CurrencyExchange, WireIn oder WireOut
  • transactionFlow: der Verarbeitungsablauf, nützlich fürs Routing
  • data: die Transaktion selbst, mit externalId, internalId und Status

Events

Worüber Sie benachrichtigt werden

  • Karteneinzahlung

    transactionType
    PayIn
    Was es Ihnen sagt
    Genehmigt, abgeschlossen, abgelehnt, erstattet oder per Chargeback zurückgebucht
  • Einzahlung per Banküberweisung oder lokaler Methode

    transactionType
    PayIn
    Was es Ihnen sagt
    Finaler Status, nachdem der Zahler in seiner Bank- oder Wallet-App bestätigt hat
  • Virtuelles Konto

    transactionType
    VirtualAccount
    Was es Ihnen sagt
    Konto angelegt sowie jede eingegangene Zahlung
  • Abonnement

    transactionType
    Subscription
    Was es Ihnen sagt
    Lebenszyklus des Abos; jede Belastung kommt zusätzlich als PayIn-Event
  • Auszahlung

    transactionType
    PayOut
    Was es Ihnen sagt
    Statusänderungen im Auszahlungsablauf bis zum Abschluss
  • Devisentausch

    transactionType
    CurrencyExchange
    Was es Ihnen sagt
    Ergebnis einer Umrechnung zwischen Ihren Guthaben
  • Wire In

    transactionType
    WireIn
    Was es Ihnen sagt
    Ihrem Konto gutgeschriebene Mittel, in Fiat oder USDC/USDT
  • Wire Out

    transactionType
    WireOut
    Was es Ihnen sagt
    Auszahlung versendet; Krypto-Wire-Outs enthalten den Blockchain-Transaktionshash

Vollständige Schemas und Statuscodes je Event finden Sie in der Webhook-Referenz auf docs.localpayment.com.

Sicherheit

Jede Signatur prüfen

Jeder Request trägt x-Signature: HMAC-SHA256, gefolgt von einem Hex-Digest des Roh-Bodys, berechnet mit Ihrem Webhook-Secret. Berechnen Sie ihn neu und vergleichen Sie, bevor Sie dem Payload vertrauen.

  • Lesen Sie den Roh-Body: Es ist JSON, gesendet als Content-Type text/plain
  • Entfernen Sie das Präfix „HMAC-SHA256 “ und vergleichen Sie mit einer timing-sicheren Funktion
  • Lehnen Sie Abweichungen mit 401 ab und loggen Sie nie den vollständigen Payload
webhook.js
// Express-Empfänger für Localpayment-Webhooks (Node.js 18+).
import crypto from 'node:crypto';
import express from 'express';
import { jobQueue } from './queue.js'; // Ihre eigene asynchrone Job-Queue

const app = express();

// Webhook-Secret beim Start aus Ihrem Secrets Manager laden. Niemals hartcodieren.
const WEBHOOK_SECRET = process.env.LP_WEBHOOK_SECRET;
if (!WEBHOOK_SECRET) throw new Error('LP_WEBHOOK_SECRET is not configured');

function hasValidSignature(rawBody, header) {
  if (typeof rawBody !== 'string') return false;
  // Header-Format: "x-Signature: HMAC-SHA256 <hex>". Zuerst das Präfix entfernen.
  const received = String(header ?? '').replace(/^HMAC-SHA256\s+/i, '').trim();
  if (!/^[0-9a-f]{64}$/i.test(received)) return false;

  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(rawBody, 'utf8').digest();
  return crypto.timingSafeEqual(Buffer.from(received, 'hex'), expected);
}

// Der Body ist JSON mit Content-Type text/plain: Behalten Sie den Rohtext für den HMAC.
app.post('/webhooks/localpayment', express.text({ type: '*/*', limit: '1mb' }), (req, res) => {
  if (!hasValidSignature(req.body, req.get('x-signature'))) return res.sendStatus(401);

  let event;
  try {
    event = JSON.parse(req.body);
  } catch {
    return res.sendStatus(400);
  }

  res.sendStatus(200); // schnell bestätigen, vor jeder aufwendigen Verarbeitung
  // Asynchron verarbeiten. Nach internalId/externalId + Status deduplizieren,
  // damit eine erneute Zustellung nur einmal angewendet wird. Nie den vollständigen Payload loggen.
  jobQueue.enqueue(event);
});

Zuverlässige Verarbeitung

Gebaut für Wiederholungen und reale Netzwerke

  • Schnell bestätigen

    Antworten Sie mit 200, sobald die Signatur stimmt, und erledigen Sie die aufwendige Arbeit in einem Hintergrundjob.

  • Mit Wiederholungen rechnen

    Erhalten wir kein 200, wiederholen wir mit exponentiellem Backoff. Ihr Handler muss mehrfach ausführbar sein.

  • Deduplizieren

    Verarbeiten Sie nach internalId oder externalId plus Status, damit eine erneute Zustellung nur einmal angewendet wird.

  • Keine Reihenfolge voraussetzen

    Vergleichen Sie den eingehenden Status mit dem gespeicherten, bevor Sie ihn anwenden, und setzen Sie eine Transaktion nie zurück.

  • Mit der API bestätigen

    Im Zweifel fragen Sie GET /api/transactions/{externalId}/status nach dem aktuellen Stand einer Transaktion ab.

  • Sicher loggen

    Loggen Sie Event-Typen, IDs und Status – niemals vollständige Payloads, Tokens oder personenbezogene Daten.

Betrieb

Jede Zustellung im Business Portal sehen

Benachrichtigungsberichte zeigen, was an Ihre Endpunkte gesendet wurde, sodass Support und Engineering Probleme lösen können, ohne Server-Logs zu durchforsten.

  • Zustellprotokoll der an Ihre Endpunkte gesendeten Benachrichtigungen
  • Transaktionssuche und detaillierte Aktivitätsberichte
  • Webhooks, IP-Allowlist und Nutzer an einem Ort verwaltet

FAQ zu Webhooks

Woran erkenne ich, dass ein Webhook wirklich von Localpayment stammt?

Prüfen Sie den Header x-Signature: Berechnen Sie den HMAC-SHA256 des Roh-Bodys mit Ihrem Webhook-Secret neu und vergleichen Sie beide mit einer timing-sicheren Funktion. Zusätzlich können Sie jedem Benachrichtigungseintrag eigene Header für Ihr Gateway hinzufügen.

Wie oft werden fehlgeschlagene Zustellungen wiederholt?

Zustellungen ohne 200-Antwort werden mit exponentiellem Backoff wiederholt. Legen Sie Ihren Handler auf mehrere Versuche aus und prüfen Sie die Zustellhistorie in den Benachrichtigungsberichten im Business Portal.

Warum ist der Content-Type text/plain?

Der Body ist JSON, gesendet als text/plain. Lesen Sie ihn als Rohtext, prüfen Sie die Signatur über genau diese Bytes und parsen Sie ihn erst danach.

Kann ich verschiedene Länder an verschiedene Endpunkte senden?

Ja. Jeder Benachrichtigungseintrag ist nach Land (oder All) und Konto eingegrenzt, sodass Sie Märkte oder Geschäftsbereiche an separate URLs leiten können.

Was sollte mein Endpunkt zurückgeben?

Einen 200-Status – so schnell wie möglich und vor jeder länger laufenden Verarbeitung. Ohne 200 gilt die Zustellung als fehlgeschlagen und wird wiederholt.

Richten Sie Ihren ersten Webhook ein

Konfigurieren Sie einen Stage-Endpunkt, lösen Sie eine Testeinzahlung aus und prüfen Sie die Signatur von Anfang bis Ende.

Wie können wir helfen?

Ihr Exemplar herunterladen

Hinterlassen Sie Ihre Daten und erhalten Sie sofort die vollständige Ausgabe.