PfotenCard API & Webhooks

Permissions (scopes)

• read:customers – read customers, dogs and levels
• write:customers – create customers and change contact details
• read:appointments – read appointments and bookings
• read:transactions – read transactions

Pagination

Lists are sorted by ID in ascending order and return data, has_more and next_cursor. For the next page, append starting_after=<next_cursor>. limit: 1–100 (appointments, bookings, transactions up to 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"
}

Error

Errors always come in the same format with the appropriate 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 is missing, wrong, revoked or expired
• 402 subscription_inactive – the school's PfotenCard subscription is not active
• 403 plan_required – the module is not included in the booked plan
• 403 module_disabled – the school has switched the module off
• 403 insufficient_scope – permission missing
• 400 invalid_parameter, 404 not_found, 409 already_exists
• 429 rate_limited – more than 120 requests per minute and key

You set up webhooks in the settings: enter an https address, choose events, done. PfotenCard then sends a POST with JSON to this address for each event – usually a few seconds after the action.

Structure of a message

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 has the same format as the respective API resource and shows the state at the time of delivery. If a record has been deleted by then, data contains the state at the time of the event and "deleted": true. Use the event's id to detect duplicate deliveries – in rare cases a message may arrive more than once.

Verify signature

The PfotenCard-Signature header contains a timestamp t and v1 = HMAC-SHA256(secret, t + "." + raw body) as a hex value. Verify using the unmodified body and reject messages whose timestamp is older than about five minutes.

// 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);

Response, retries, pausing

Respond within 8 seconds with a 2xx status. Redirects are not followed. If a delivery fails, PfotenCard retries after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours. Every attempt is listed in the log in the settings and can be triggered again there. If ten events in a row fail to arrive, the webhook is paused and the school's admins are notified. Logs are kept for 30 days.

For security reasons only public https addresses are allowed – no internal networks, no localhost.