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
- 09:41:02.11409:41:02PayIn100 INPROGRESS20084 ms
- 09:41:05.90209:41:05PayIn200 COMPLETED20091 ms
- 09:42:18.33009:42:18PayOut100 INPROGRESS20077 ms
- 09:42:40.01809:42:40PayOut200 COMPLETED20088 ms
- 09:43:00.55109:43:00VirtualAccount200 COMPLETED20080 ms
POST https://example-merchant.com/webhooks/localpayment
x-Signature: HMAC-SHA256 3f9a1c0e…b47e2b
{ "transactionType": "PayIn", "transactionFlow": "DIRECT",
"data": { "externalId": "order_8F2K-1043",
"status": { "code": "200", "description": "COMPLETED" } } }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.
- 01
Benachrichtigungen öffnen
Gehen Sie im Business Portal zu Configurations → Clients → Notifications.
- 02
HTTPS-URL hinzufügen
Registrieren Sie den öffentlichen HTTPS-Endpunkt auf Ihren Servern, der die Events empfängt.
- 03
Eintrag eingrenzen
Wählen Sie ein Land oder All sowie das Konto, zu dem die Benachrichtigungen gehören.
- 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
// 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
Übersicht
USD
1.284.560,00
+4,2 %
BRL
3.420.118,40
+12,8 %
MXN
8.905.332,10
+6,1 %
- Pay-in · Pixorder_8F2K-1043+ R$ 1.250,00
- Auszahlung · SPEIseller_0921− MX$ 18.400,00
- FX · BRL → USDfx_3b7q250.000,00 USD
- Pay-in · Bre-Border_9A1C-2210+ COP 890.000
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.
Verwandte Themen
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.

HMAC-SHA256-Signaturen