Zum Hauptinhalt springen

​
Überblick

Ovra sendet HTTPS-POST-Anfragen an von Ihnen registrierte URLs, wenn Events auftreten — Zahlungen, Intents, Cards, Agents, Streitfälle und mehr. Die Payloads sind JSON und enthalten einen Event-Namen sowie strukturierte data.

​
Einrichtung

curl -X POST https://api.getovra.com/webhooks \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["transaction.completed", "intent.approved", "intent.denied"]
  }'
Abonnieren Sie einzelne Event-Namen, oder nutzen Sie "*", um alle Events zu erhalten (in Produktion mit Vorsicht verwenden).

​
Event-Katalog

Die Payload-Struktur ist einheitlich: Der JSON-Body enthält event, createdAt und data (eventspezifische Felder). Derselbe event-Wert steht zusätzlich in X-Ovra-Event.

​
Transactions

EventWann
transaction.completedErfolgreicher Checkout (Browser-Fill oder Ledger-Execute) oder Issuer-Settlement-/Refund-Flows, die einen Zahlungsdatensatz abschließen
transaction.authorizationKartenautorisierung vom Issuer-Webhook akzeptiert
transaction.declinedAutorisierung abgelehnt (z. B. Policy-Simulation oder unzureichendes Guthaben in Testpfaden)

​
Intents

EventWann
intent.createdNeuer Intent angelegt
intent.approvedGenehmigt (Policy oder manuell)
intent.deniedAbgelehnt
intent.cancelledVor der Zahlung abgebrochen
intent.expiredTTL abgelaufen ohne Abschluss

​
Cards

EventWann
card.issuedNeue virtuelle Karte bereitgestellt
card.fundedAgent-Funding hat das Ausgabelimit erhöht
card.frozenKarte eingefroren
card.unfrozenKarte reaktiviert
card.closedKarte dauerhaft geschlossen
card.rotatedKarten-Credentials rotiert

​
Agents

EventWann
agent.createdNeuer Agent angelegt
agent.frozenAgent eingefroren
agent.unfrozenAgent reaktiviert

​
Streitfälle und Verifikation

EventWann
dispute.createdStreitfall eröffnet
dispute.updatedStreitfall oder Nachweise aktualisiert
dispute.resolvedStreitfall geschlossen (resolved oder rejected)
verification.mismatchPost-Checkout-Verifikation stimmte nicht mit dem Intent überein
Die Subscription-API kann zusätzliche Event-Namen oder Wildcards für Vorwärtskompatibilität akzeptieren; behandeln Sie unbekannte Events defensiv, wenn Sie breit abonnieren (z. B. "*").

​
Header und Verifikation

Jede Zustellung enthält:
HeaderZweck
X-Ovra-EventEvent-Name (wie event im JSON-Body)
X-Ovra-TimestampUnix-Sekunden zum Zeitpunkt der Signierung der Anfrage
X-Ovra-Signaturesha256=<hex> HMAC der Signaturzeichenkette (siehe unten)
Content-Typeapplication/json
Signaturzeichenkette: Verketten Sie den Timestamp, einen einzelnen Punkt (.) und den rohen Request-Body (Bytes wie gesendet), und berechnen Sie HMAC-SHA256 mit Ihrem Webhook-Secret. Vergleichen Sie das Ergebnis mit dem Hex-Digest in X-Ovra-Signature (nach dem Präfix sha256=). Lehnen Sie Anfragen mit veralteten Timestamps ab, wenn Sie Replay-Fenster erzwingen.

​
Retry-Policy

Fehlgeschlagene Zustellungen (Nicht-2xx, Timeouts oder Verbindungsfehler) werden mit exponentiellem Backoff wiederholt:
  • Verzögerungen: 1 Minute, 5 Minuten, 15 Minuten, 1 Stunde, 4 Stunden
  • Maximal 5 Versuche pro Zustellung
Idempotente Handler werden empfohlen: Dasselbe logische Event kann nach einem Timeout erneut gesendet werden, auch wenn Ihr Server den ersten Versuch bereits verarbeitet hat.