Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://docs.getovra.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks sind wie Ovra deinen Systemen mitteilt dass etwas passiert ist. Jede state-ändernde Operation feuert einen. Deliveries sind HMAC-SHA256-signiert, retried auf einem plan-tier-aware Backoff-Schedule und SSRF-checked gegen Private-IPs und Metadata-Endpoints.

​
Subscriben

curl -X POST https://api.getovra.com/webhooks \
  -H "Authorization: Bearer $OVRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/ovra/webhook",
    "events": ["transaction.completed", "intent.approved", "claim.request.paid"],
    "description": "Production-Webhook"
  }'
["*"] für alle Events. URL-Constraints (isBlockedWebhookUrl):
  • HTTPS oder HTTP (HTTPS in Prod stark empfohlen)
  • Kein localhost
  • Kein RFC 1918 (10.0.0.0/8, 172.16/12, 192.168/16)
  • Kein Link-local (169.254.0.0/16) oder Metadata-Endpoints (169.254.169.254, metadata.google.internal)
  • DNS-Rebinding-Check zur Delivery-Time

​
Event-Katalog

~50 Event-Typen über diese Kategorien. Source of Truth: apps/api/src/services/webhook.ts WebhookEvent-Union.
intent.created · intent.approved · intent.denied · intent.expired · intent.cancelled · intent.matched (reserviert) · intent.mismatched (reserviert)
transaction.created · transaction.updated · transaction.authorization · transaction.settlement · transaction.settled · transaction.completed · transaction.declined · transaction.refunded
card.issued · card.activated · card.frozen · card.unfrozen · card.closed · card.rotated · card.funded · card.shipped · card.limits_changed · card.details_changed
card_limit_request.updated
wallet.created · wallet.funded · wallet.credited
transfer.completed · transfer.failed · transfer.split.completed
risk.agent_frozen · risk.review_required · risk.alert_created · risk.denied · risk.velocity_alert · risk.geo_impossible
agent.created · agent.frozen · agent.unfrozen
claim.request.created · claim.request.paid · claim.request.expired · claim.request.cancelled
dispute.created · dispute.updated · dispute.resolved
mpp.credential.minted · mpp.credential.consumed · mpp.credential.expired (reserviert) · mpp.transaction.completed
verification.mismatch · mobile_wallet.updated · payment.updated · receipt.updated · bill.updated · cardholder.updated

​
Delivery-Format

Headers:
HeaderWert
X-Ovra-EventEvent-Name
X-Ovra-TimestampUnix-Sekunden zur Sign-Time
X-Ovra-Delivery-IdEindeutig pro Versuch
X-Ovra-Signaturesha256=<hex> HMAC-SHA256 von {deliveryId}.{timestamp}.{rawBody}
X-Request-IdKorrelation zurück zum Originating-Request
Body: 
{
  "event": "transaction.completed",
  "createdAt": "2026-04-20T12:34:56.789Z",
  "data": {
    "transactionId": "tx_...",
    "agentId": "ag_...",
    "intentId": "int_...",
    "amountEuros": 4.51,
    "merchant": "hetzner.com",
    "status": "completed"
  }
}

​
Signatur verifizieren

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(req: { headers: Record<string,string>, rawBody: Buffer }, secret: string) {
  const sig = req.headers["x-ovra-signature"] ?? "";
  const ts  = req.headers["x-ovra-timestamp"] ?? "";
  const id  = req.headers["x-ovra-delivery-id"] ?? "";
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(`${id}.${ts}.${req.rawBody.toString("utf8")}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

​
Retry-Policy (plan-tier-aware)

TierMax VersucheBackoffDead-Letter
basic1––
full1––
full_retry51m · 5m · 15m · 1h · 4h–
full_dlq5Wie oben✓
Background-Poller läuft alle 30s, klaut Rows via FOR UPDATE SKIP LOCKED damit Multi-Instance-API-Hosts nie doppelt deliveren.
PlanWebhook-Tier
Freebasic
Starterfull
Businessfull_retry
Enterprisefull_dlq

​
Best Practices

  • Signaturen verifizieren bevor verarbeitet wird — niemals dem Body unsigned vertrauen.
  • Idempotente Handler — derselbe Event kann mehrfach delivered werden.
  • Schnell acknowledgen — 2xx in 30s zurückgeben. Slow Work in Queue verschieben.
  • Timestamp-Window prüfen um sehr alte Replays abzulehnen.

​
Weiter

Intelligenz

Audit + Decision-Logs ergänzen Webhooks für Forensik.

Sandbox

Signaturverifikation End-to-End testen.