VPOS.am Webhooks: signierte Zahlungsereignisse

Webhooks

Prüfen Sie X-VPOS-Signature über den unveränderten Request Body, speichern Sie die Event ID, antworten Sie schnell mit 2xx und verarbeiten Sie Wiederholungen idempotent.

Version

API v1

Zuletzt geprüft

16. Sept. 2026

Status

Vertrag veröffentlicht

Überblick

Der öffentliche Webhook-Vertrag von VPOS.am liefert das signierte Event payment.status_changed mit serverseitig verifiziertem Zahlungsstatus.

HTTP / HMAC

Signaturvertrag

Prüfen Sie den zeitgestempelten HMAC über den unveränderten Request-Body, bevor Sie den Payload auswerten oder den Geschäftsstatus ändern.

X-VPOS-Event-Id: <event_id>
X-VPOS-Event-Type: payment.status_changed
X-VPOS-Webhook-Timestamp: <unix_timestamp>
X-VPOS-Signature: t=<unix_timestamp>,v1=<current_secret_hmac>[,v1=<grace_secret_hmac>]

signed_payload = <timestamp>.<raw_request_body>
signature = HMAC-SHA256(webhook_secret, signed_payload)

Feld	Vertrag
Kopfzeile	`X-VPOS-Signature`
Signierter Wert	`<timestamp>.<raw_request_body>`
Algorithmus	`HMAC-SHA256`
Timestamp-Toleranz	`5 Minuten`
Zustell-Timeout	`5 Sekunden`
Standardmäßige Höchstzahl der Versuche	`8 Versuche`
Wiederholungsplan	`Exponentiell ab 30 Sekunden, begrenzt auf 1 Stunde`
Bestätigung	`Schnell eine 2xx-Antwort zurückgeben`
Secret-Rotation	`Der Header kann mehrere v1-Werte enthalten. Akzeptieren Sie das Ereignis nur, wenn mindestens einer zum aktuellen oder noch gültigen Grace-Secret passt.`
Verarbeitung	`Signatur prüfen, event id speichern und danach Seiteneffekte in die Warteschlange stellen.`

Öffentlicher Event-Vertrag

Aktuell ist nur payment.status_changed öffentlich dokumentiert. fiscalStatus ist Teil von data.payment, verspricht aber keine separaten öffentlichen Fiscal- oder Reconciliation-Events.

Signatur und erneute Zustellung

Berechnen Sie HMAC-SHA256 über <timestamp>.<raw_request_body> mit dem Merchant Webhook Secret, lehnen Sie alte Timestamps ab und führen Sie Downstream-Aktionen über eine idempotente Queue aus.

So nutzen Sie diese Seite

Webhooks hilft, das Zahlungsszenario zwischen Business, Entwicklung und Operations abzustimmen. Vor dem Start sollten Vertriebskanal, Provider-Route, Webhook-Verantwortung, Statusprüfung und Kundensupport nach der Zahlung festgelegt werden. Testzahlung, Rückerstattung und Abgleich sollten dabei gemeinsam geprüft und dokumentiert werden.