Skip to content

Webhooks

Ereignisse empfangen, Signaturen prüfen, Wiederholungen verstehen.

Endpunkt anlegen

Unter Entwickler → Webhooks oder per API:

curl https://api.freika.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $FREIKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://deinshop.ch/webhooks/freika",
    "events": ["payment.succeeded", "payment.failed", "refund.succeeded", "payout.paid"]
  }'

Die Antwort enthält das secret (beginnt mit whsec_). Es wird nur einmal angezeigt.

Ereignisse

EreignisWann
payment.createdZahlung erstellt
payment.authorizedBetrag reserviert
payment.succeededZahlung erfolgreich
payment.failedZahlung abgelehnt oder fehlgeschlagen
payment.canceledZahlung abgebrochen oder storniert
refund.createdRückerstattung ausgelöst
refund.succeeded, refund.failedRückerstattung ausgeführt oder gescheitert
payout.paidAuszahlung abgerechnet
chargeback.created, chargeback.updatedRückbuchung eingegangen oder entschieden
terminal.created, terminal.linkedTerminal angelegt oder mit einem Gerät gekoppelt
terminal.activated, terminal.deactivatedTerminal aktiviert oder deaktiviert
terminal.batch_closedTagesabschluss erstellt
payment_link.created, payment_link.completedZahlungslink erstellt oder Einmal-Link bezahlt

Ohne Auswahl ("events": []) oder mit "*" erhält der Endpunkt alle Ereignisse.

Aufbau

{
  "id": "evt_01J9X3B7",
  "type": "payment.succeeded",
  "created_at": "2026-09-10T09:01:12Z",
  "environment": "live",
  "data": { "id": "pay_01J9X3A4Q6", "status": "succeeded", "amount": 8900 }
}

Signatur prüfen

Jede Zustellung trägt den Header Freika-Signature:

Freika-Signature: t=1757494872,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Prüfe so:

  1. Nimm den Rohtext des Bodys (nicht neu serialisieren).
  2. Bilde t + "." + body und berechne HMAC-SHA256 mit deinem secret.
  3. Vergleiche mit v1 in konstanter Zeit.
  4. Lehne Ereignisse ab, deren t älter als 5 Minuten ist.
import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret: string, header: string, rawBody: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Antworten und Wiederholungen

Antworte innert 10 Sekunden mit 2xx. Alles andere gilt als Fehlschlag. Wir wiederholen mit wachsendem Abstand bis zu 3 Tage lang: nach 1, 5, 30 Minuten, dann stündlich, dann alle 6 Stunden. Ereignisse können mehrfach ankommen; verarbeite sie idempotent anhand von id.

Zustellprotokoll

Unter Entwickler → Webhooks → Zustellungen siehst du jede Zustellung mit Antwortcode und kannst sie erneut senden. Per API:

EndpunktZweck
GET /v1/webhook_endpoints/{id}/deliveriesZustellungen mit Status, Versuchen und letztem Fehler
POST /v1/webhook_endpoints/{id}/testTestereignis sofort senden, Ergebnis in der Antwort
POST /v1/webhook_endpoints/{id}/roll_secretNeues Secret, das alte gilt ab sofort nicht mehr
GET /v1/events, GET /v1/events/{id}Ereignisse der letzten Zeit nachlesen
POST /v1/events/{id}/resendEreignis erneut senden (optional an einen endpoint)

Testen

Testereignis senden im Dashboard schickt ein payment.succeeded mit Beispieldaten an deinen Endpunkt. In der Sandbox kannst du Zahlungen durchspielen und die echten Ereignisse empfangen.