Webhooks
BetaErhalten 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):
- 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. - Kopieren Sie das Signatur-Secret, das mit
whsec_beginnt. Es wird nur einmal angezeigt; danach zeigt der Bildschirm nur noch die letzten vier Zeichen. - 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:
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):
{
"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, mittrue, bei der Zustellung über die Schaltfläche „Test senden“.donnees.client:{ id, prenom }, dazutelephoneundemailnur, wenn der Kunde sie angegeben hat;nullbei einem Gutschein oder einem Prepaid-Paket.- Beträge (
montant,prix) sind in Cent angegeben, als Ganzzahlen, mit ihrerdevise(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.
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
tab, 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();
});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
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.
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=4346dff69a3e9e25937b22ec031a8eaf8cfce3baca4dfb932865682b8f891f1dAntworten 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 aufcree_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.