Zum Inhalt springen

Für KI-Agenten: Das Verzeichnis der Dokumentation steht unter https://stampywallet.com/de/docs/llms.txt, die gesamte Dokumentation in einer Datei unter https://stampywallet.com/de/docs/llms-full.txt, und diese Seite gibt es als Markdown: https://stampywallet.com/de/docs/api/webhooks.md (oder mit dem Header Accept: text/markdown).

StampyWalletDocs
API und Webhooks / Webhooks / WebhooksAls Markdown ansehen

Webhooks

Beta

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, oder empfangen Sie die Verkäufe Ihrer Kasse 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:

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):

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.

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.
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();
});

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.

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 ZustellungBedeutung
en_attenteNoch nicht versucht
echecDer letzte Versuch ist fehlgeschlagen; ein weiterer ist geplant
livreEin 2xx wurde empfangen
abandonneAcht 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.

War diese Seite hilfreich?