# Webhooks

> Für KI-Agenten: Das vollständige Verzeichnis der Dokumentation steht unter [llms.txt](https://stampywallet.com/de/docs/llms.txt), die gesamte Dokumentation passt in eine Datei: [llms-full.txt](https://stampywallet.com/de/docs/llms-full.txt). Seite online: https://stampywallet.com/de/docs/api/webhooks/

Erhalten Sie bei jedem Besuch, jeder Prämie oder neuen Karte einen signierten HTTP-Aufruf auf Ihrem Server, in Zapier, Make oder n8n, und prüfen Sie seine HMAC-Signatur.

Ein Webhook ist eine Adresse auf Ihrem Server, die StampyWallet bei jedem Ereignis an der Theke aufruft: ein Besuch, eine Prämie, eine neue Karte, ein verkaufter Gutschein. So verbinden Sie StampyWallet mit einer Kasse, einem CRM, einer Tabelle oder einem No-Code-Tool, ohne offizielle Integration.

> **In die andere Richtung? :** damit Ihre Kasse bei jedem Verkauf einen Stempel vergibt, nutzen Sie [`POST /v1/passages`](https://stampywallet.com/de/docs/api/besuch-erfassen/), oder [empfangen Sie die Verkäufe Ihrer Kasse](https://stampywallet.com/de/docs/api/kassen-eingang/) direkt.

## Eine Adresse einrichten

Unter **Einstellungen › Integrationen › Webhooks** (Inhaber und Manager):

1. **Fügen Sie eine öffentliche `https://`-Adresse hinzu** und haken Sie bei Bedarf die gewünschten Ereignisse an. **Kein Haken gesetzt: alle Ereignisse**, auch die, die später dazukommen.
2. **Kopieren Sie das Signatur-Secret**, das mit `whsec_` beginnt. Es wird nur einmal angezeigt; danach zeigt der Bildschirm nur noch die letzten vier Zeichen.
3. **Klicken Sie auf „Test senden“**: Ein Beispiel-`passage.cree`, markiert mit `"test": true`, geht sofort an Ihre Adresse, und der Bildschirm zeigt die erhaltene Antwort.

Der Bildschirm zeigt die letzten 20 Zustellungen (Status, Code, Dauer, Versuch) und eine Schaltfläche **Erneut senden** bei den fehlgeschlagenen. Höchstens zehn Adressen pro Geschäft; jede lässt sich deaktivieren, wieder aktivieren oder löschen.

> **Achtung :** abgelehnt werden: eine Adresse, die nicht mit `https://` beginnt, eine Adresse mit Zugangsdaten (`https://ich:geheim@…`) und jede private oder lokale Adresse (`localhost`, `10.x`, `192.168.x`…), auch wenn sie erst über DNS aufgelöst wird. Alle Ports sind erlaubt. Weiterleitungen werden nie verfolgt: Eine 3xx-Antwort zählt als Fehlschlag.

## Was Ihr Server empfängt

Eine `POST`-Anfrage in JSON, mit diesen Headern:

```http title="Header"
POST /votre/adresse HTTP/1.1
Content-Type: application/json
User-Agent: StampyWallet-Webhooks/1.0
StampyWallet-Evenement: passage.cree
StampyWallet-Id: evt_WdGHduXPRbExh0vh5eYtCjXo
StampyWallet-Signature: t=1792648365,v1=8f3c…(64 Hexadezimalzeichen)
```

Und diesen Body. Die Hülle ist für alle Ereignisse gleich; nur `donnees` ändert sich ([die Liste der Ereignisse](https://stampywallet.com/de/docs/api/ereignisse/)):

```json title="passage.cree"
{
  "id": "evt_WdGHduXPRbExh0vh5eYtCjXo",
  "type": "passage.cree",
  "cree_le": "2026-10-22T05:52:45.694Z",
  "commerce": { "id": "9f1cbdfc-df71-4fab-a554-3bdbb7c71ebf", "nom": "Le Café des Crochets" },
  "donnees": {
    "client": { "id": "40de4b86-1d7a-4cc6-add3-b7a83fa43c04", "prenom": "Inès",
                "telephone": "+33611223344", "email": "ines@example.com" },
    "passage": {
      "id": "226fdea1-ba59-49fb-93e6-60a14a765134",
      "quantite": 1,
      "montant": null,
      "devise": "EUR",
      "reference": "caisse-1",
      "source": "scan",
      "piste": "normal",
      "tampons": 1,
      "objectif": 2
    }
  }
}
```

- `id`: `evt_` gefolgt von 24 Zeichen. **Bei allen Zustellungen eines Ereignisses gleich** (Versuche, erneutes Senden, und von einer Adresse zur anderen): Das ist Ihr Schlüssel zum Entfernen von Dubletten.
- `cree_le`: der Zeitpunkt des Ereignisses (nicht der Zustellung), in ISO 8601 UTC.
- `test`: nur vorhanden, mit `true`, bei der Zustellung über die Schaltfläche „Test senden“.
- `donnees.client`: `{ id, prenom }`, dazu `telephone` und `email` nur, wenn der Kunde sie angegeben hat; `null` bei einem Gutschein oder einem Prepaid-Paket.
- Beträge (`montant`, `prix`) sind in **Cent** angegeben, als Ganzzahlen, mit ihrer `devise` (ISO 4217).
- Neue Schlüssel können hinzukommen: Ignorieren Sie, was Sie nicht kennen.

## Die Signatur prüfen

Prüfen Sie jede Anfrage, **bevor** Sie ihrem Inhalt vertrauen: Sonst könnte jeder Ihre Adresse aufrufen.

```text title="Die Berechnung"
StampyWallet-Signature: t=<Unix-Zeitstempel in Sekunden>,v1=<Signatur>
Signatur = hex( HMAC-SHA256( Schlüssel = Secret, Nachricht = "<t>.<Roh-Body>" ) )
```

- Der Schlüssel ist das **vollständige** Secret, einschließlich des Präfixes `whsec_`.
- Die Nachricht ist der Zeitstempel `t`, ein Punkt, dann der Body **so, wie er angekommen ist**, als Bytes. Parsen Sie das JSON nicht vor der Prüfung neu: Ein neu geschriebenes JSON hat nicht mehr dieselben Bytes.
- Lehnen Sie ein `t` ab, das mehr als 5 Minuten von Ihrer Uhr abweicht: Das verhindert, dass eine alte Anfrage erneut abgespielt wird.
- Der Header kann mehrere `v1=` enthalten (am Tag eines Secret-Wechsels): Es genügt, wenn eines übereinstimmt. Vergleichen Sie in konstanter Zeit.

```js title="Node.js"
const crypto = require('node:crypto');

/** corpsBrut: der empfangene Body, als Buffer (oder Text), VOR jedem JSON.parse. */
function verifierStampyWallet(secret, corpsBrut, entete, tolerance = 300) {
  let t = null;
  const v1 = [];
  for (const morceau of String(entete || '').split(',')) {
    const i = morceau.indexOf('=');
    const cle = morceau.slice(0, i).trim();
    const valeur = morceau.slice(i + 1).trim();
    if (cle === 't' && /^\d+$/.test(valeur)) t = Number(valeur);
    if (cle === 'v1') v1.push(valeur);
  }
  if (t === null || v1.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > tolerance) return false;
  const attendue = crypto.createHmac('sha256', secret)
    .update(`${t}.`).update(corpsBrut).digest('hex');
  return v1.some((s) => s.length === attendue.length
    && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(attendue)));
}

// Mit Express: auf dieser Route den Roh-Body behalten.
app.post('/stampywallet', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifierStampyWallet(process.env.STAMPYWALLET_WEBHOOK_SECRET,
    req.body, req.get('StampyWallet-Signature'));
  if (!ok) return res.status(400).end();
  const evenement = JSON.parse(req.body.toString('utf8'));
  // Dubletten über evenement.id entfernen, dann später verarbeiten
  res.status(200).end();
});
```
```python title="Python"
import hashlib
import hmac
import time

def verifier_stampywallet(secret: str, corps_brut: bytes, entete: str, tolerance: float = 300) -> bool:
    """corps_brut: die empfangenen Bytes (Flask: request.get_data()), vor jedem json.loads."""
    t, v1 = None, []
    for morceau in (entete or "").split(","):
        cle, _, valeur = morceau.strip().partition("=")
        if cle == "t" and valeur.isdigit():
            t = int(valeur)
        elif cle == "v1":
            v1.append(valeur)
    if t is None or not v1:
        return False
    if abs(int(time.time()) - t) > tolerance:
        return False
    attendue = hmac.new(secret.encode(), f"{t}.".encode() + corps_brut, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(s, attendue) for s in v1)

# Mit Flask:
# @app.post("/stampywallet")
# def recevoir():
#     if not verifier_stampywallet(os.environ["STAMPYWALLET_WEBHOOK_SECRET"],
#                                  request.get_data(),
#                                  request.headers.get("StampyWallet-Signature", "")):
#         abort(400)
#     evenement = request.get_json()
#     return "", 200
```
```php title="PHP"
<?php
function verifier_stampywallet(string $secret, string $corpsBrut, string $entete, int $tolerance = 300): bool
{
    $t = null;
    $v1 = [];
    foreach (explode(',', $entete) as $morceau) {
        $paire = explode('=', trim($morceau), 2);
        if (count($paire) !== 2) {
            continue;
        }
        if ($paire[0] === 't' && ctype_digit($paire[1])) {
            $t = (int) $paire[1];
        } elseif ($paire[0] === 'v1') {
            $v1[] = $paire[1];
        }
    }
    if ($t === null || count($v1) === 0) {
        return false;
    }
    if (abs(time() - $t) > $tolerance) {
        return false;
    }
    $attendue = hash_hmac('sha256', $t . '.' . $corpsBrut, $secret);
    foreach ($v1 as $s) {
        if (hash_equals($attendue, $s)) {
            return true;
        }
    }
    return false;
}

// der Roh-Body, vor json_decode
$corps = file_get_contents('php://input');
$ok = verifier_stampywallet(getenv('STAMPYWALLET_WEBHOOK_SECRET'), $corps,
    $_SERVER['HTTP_STAMPYWALLET_SIGNATURE'] ?? '');
```

### Testvektor

Zum Prüfen Ihres Codes: Mit diesen Werten und einer unendlichen Toleranz (`Infinity`, `float("inf")`, `PHP_INT_MAX`) muss die Funktion wahr zurückgeben. Der Body steht in einer einzigen Zeile, ohne abschließenden Zeilenumbruch, und enthält absichtlich ein „é“: Die Signatur bezieht sich auf die UTF-8-Bytes.

```text title="Vektor"
secret : whsec_5WZbPq8rLk2N7xYdTf3Hc9JmVg4RsQe1
t      : 1761134400
corps  : {"id":"evt_4fK9mQ2xT7bL1nR8vZ3cW6yH","type":"passage.cree","cree_le":"2026-10-22T12:00:00.000Z","commerce":{"id":"9b2f6c1e-4d3a-4f7b-8e21-5a6c7d8e9f01","nom":"Le Café du Coin"},"donnees":{"client":{"id":"3c1d2e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f","prenom":"Camille"},"passage":{"id":"7e8f9a0b-1c2d-4e3f-9a4b-5c6d7e8f9a0b","quantite":1,"montant":null,"devise":"EUR","reference":null,"source":"scan","piste":"normal","tampons":4,"objectif":10}}}
v1     : 4346dff69a3e9e25937b22ec031a8eaf8cfce3baca4dfb932865682b8f891f1d
en-tête: t=1761134400,v1=4346dff69a3e9e25937b22ec031a8eaf8cfce3baca4dfb932865682b8f891f1d
```

## Antworten und Wiederholungen

- Antworten Sie mit einem **2xx-Code in weniger als 10 Sekunden**. Der Body Ihrer Antwort wird ignoriert. Antworten Sie schnell und erledigen Sie lange Arbeiten danach.
- Andernfalls gibt es insgesamt **acht Versuche**: den ersten sofort, dann nach 1 Min., 5 Min., 30 Min., 2 Std., 5 Std., 8 Std. und 8 Std. Der letzte geht etwa 23,5 Stunden nach dem ersten raus; nach dem achten Fehlschlag wird die Zustellung aufgegeben.
- Nach **50 Fehlschlägen in Folge** wird eine Adresse **deaktiviert**, und der Inhaber des Geschäfts erhält eine E-Mail. Aktivieren Sie sie wieder, sobald Ihr Server repariert ist: Ihr Zähler beginnt dann bei null.
- Die Testzustellung wird nur einmal versucht und zählt nicht zu den Fehlschlägen.
- **Erneut senden** schickt dasselbe Ereignis noch einmal (dieselbe `id`, dieselben Bytes), mit einer neuen Signatur.
- **Mindestens einmal, ohne garantierte Reihenfolge**: Ein Ereignis kann zweimal ankommen, entfernen Sie Dubletten über `StampyWallet-Id`; zwei kurz aufeinanderfolgende Ereignisse können in falscher Reihenfolge ankommen, verlassen Sie sich auf `cree_le`.
- Zustellungen bleiben 30 Tage im Protokoll.

| Status einer Zustellung | Bedeutung |
|---|---|
| `en_attente` | Noch nicht versucht |
| `echec` | Der letzte Versuch ist fehlgeschlagen; ein weiterer ist geplant |
| `livre` | Ein 2xx wurde empfangen |
| `abandonne` | Acht Fehlschläge, oder Adresse deaktiviert, oder durch erneutes Senden ersetzt |

> **Ohne Code :** Zapier, Make und n8n empfangen diese Webhooks so, wie sie sind: Tragen Sie die Adresse ihres „Webhook“-Auslösers als Adresse ein. Die Schritt-für-Schritt-Anleitungen finden Sie unter [Kasse anbinden](https://stampywallet.com/de/docs/api/kasse-anbinden/#sans-code).
