PfotenCard API & Webhooks

Berechtigungen (Scopes)

• read:customers – Kunden, Hunde und Level lesen
• write:customers – Kunden anlegen und Kontaktdaten ändern
• read:appointments – Termine und Buchungen lesen
• read:transactions – Transaktionen lesen

Seitenweises Abrufen

Listen sind nach ID aufsteigend sortiert und liefern data, has_more und next_cursor. Für die nächste Seite starting_after=<next_cursor> anhängen. limit: 1–100 (Termine, Buchungen, Transaktionen bis 500).

GET https://api.pfotencard.de/api/v1/customers?limit=50&starting_after=1234

{
  "data": [ { "id": 1240, "first_name": "Kira", ... } ],
  "has_more": true,
  "next_cursor": "1289"
}

Fehler

Fehler kommen immer im selben Format mit passendem HTTP-Status:

HTTP/1.1 403 Forbidden
{ "error": { "code": "insufficient_scope", "message": "Dem API-Key fehlt die Berechtigung \"read:transactions\"." } }

• 401 unauthorized / key_expired – Key fehlt, ist falsch, widerrufen oder abgelaufen
• 402 subscription_inactive – das PfotenCard-Abo der Schule ist nicht aktiv
• 403 plan_required – das Modul ist im gebuchten Tarif nicht enthalten
• 403 module_disabled – die Schule hat das Modul ausgeschaltet
• 403 insufficient_scope – Berechtigung fehlt
• 400 invalid_parameter, 404 not_found, 409 already_exists
• 429 rate_limited – mehr als 120 Anfragen pro Minute und Key

Webhooks richtest du in den Einstellungen ein: https-Adresse eintragen, Ereignisse wählen, fertig. PfotenCard schickt dann für jedes Ereignis ein POST mit JSON an diese Adresse – in der Regel wenige Sekunden nach der Aktion.

Aufbau einer Nachricht

POST /dein-webhook HTTP/1.1
Content-Type: application/json
PfotenCard-Event: booking.created
PfotenCard-Delivery: 5821
PfotenCard-Signature: t=1790241234,v1=5f2b…c9

{
  "id": "evt_10422",
  "type": "booking.created",
  "created_at": "2026-09-24T09:13:54.000Z",
  "school": "deine-hundeschule",
  "data": {
    "id": 7788, "appointment_id": 912, "customer_id": 1240, "dog_id": 881, "dog_name": "Fips",
    "status": "confirmed", "attended": false, "billed": false,
    "appointment": { "id": 912, "title": "Welpengruppe", "start": "2026-09-26T08:00:00.000Z", "end": "2026-09-26T09:00:00.000Z" }
  }
}

data hat dasselbe Format wie die jeweilige API-Ressource und zeigt den Stand zum Zeitpunkt der Zustellung. Ist ein Datensatz bis dahin gelöscht, enthält data den Stand zum Ereigniszeitpunkt und "deleted": true. Nutze id des Ereignisses, um doppelte Zustellungen zu erkennen – in seltenen Fällen kann eine Nachricht mehr als einmal ankommen.

Signatur prüfen

Der Header PfotenCard-Signature enthält einen Zeitstempel t und v1 = HMAC-SHA256(Geheimnis, t + "." + roher Body) als Hex-Wert. Prüfe mit dem unveränderten Body und lehne Nachrichten ab, deren Zeitstempel älter als etwa fünf Minuten ist.

// Node.js / Express
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.PFOTENCARD_WEBHOOK_SECRET; // whsec_…

app.post('/pfotencard-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('PfotenCard-Signature') || '';
  const t = /t=(\d+)/.exec(header)?.[1];
  const v1 = /v1=([0-9a-f]{64})/.exec(header)?.[1];
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(400);

  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.${req.body}`).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) return res.sendStatus(400);

  const event = JSON.parse(req.body.toString('utf8'));
  // … verarbeiten (idempotent anhand event.id)
  res.sendStatus(200);
});

# PHP
$payload = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([0-9a-f]{64})/', $_SERVER['HTTP_PFOTENCARD_SIGNATURE'] ?? '', $m);
$expected = hash_hmac('sha256', $m[1] . '.' . $payload, getenv('PFOTENCARD_WEBHOOK_SECRET'));
if (!$m || !hash_equals($expected, $m[2]) || abs(time() - (int)$m[1]) > 300) { http_response_code(400); exit; }
$event = json_decode($payload, true);

Antwort, Wiederholungen, Pausieren

Antworte innerhalb von 8 Sekunden mit einem Status 2xx. Weiterleitungen werden nicht verfolgt. Schlägt eine Zustellung fehl, versucht PfotenCard es nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 6 Stunden und 24 Stunden erneut. Jeder Versuch steht im Protokoll in den Einstellungen und lässt sich dort erneut auslösen. Kommen zehn Ereignisse in Folge nicht an, wird der Webhook pausiert und die Admins der Schule werden benachrichtigt. Protokolle werden 30 Tage aufbewahrt.

Aus Sicherheitsgründen sind nur öffentliche https-Adressen erlaubt – keine internen Netze, kein localhost.