Webhooks und Lieferprotokoll
Leiten Sie Ereignisse weiter, mit Signaturen und Wiederholversuchen.
Der Webhook meldet deinem externen System in Echtzeit, was in stmpr passiert: ein neuer Gast, ein Stempel, der Status Belohnung bereit oder eine Einlösung.
Jede Anfrage wird so signiert, dass das empfangende System überprüfen kann, dass sie tatsächlich vom stmpr gesendet wurde. Wenn die Lieferung fehlschlägt, verzögert das System den erneuten Versuch.
Das Lieferprotokoll zeigt das Ereignis, die Zeit, den Antwortcode und die Ergebnisse des erneuten Versuchs.
https://stmpr.io/dashboard/developers · Webhooks
Schritt für Schritt
- Gehe zur Webhooks-Seite im Menü Integrationen.
- Füg einen HTTPS-Endpunkt hinzu und wähle die Ereignisse aus, die du weiterleiten willst.
- Speichere das Signing-Geheimnis in der sicheren Konfiguration des Hostsystems.
- Schick ein Testereignis und prüfe Signatur, Anfragetext und die erfolgreiche 2xx-Antwort.
- Beobachte nach dem Livegang das Zustellprotokoll. Bei einem wieder erreichbaren Endpunkt werden fehlgeschlagene Zustellungen erneut versucht.
Was eine Webhook-Anfrage enthält
- Anfragekörper: der Name des Ereignisses (event), der Zeitstempel created_at und das Objekt data.
- data.wallet: ID und Name der Treuekarte.
- data.customer: ID des Gastes, vierstelliger Code, Anzahl der Stempel, benötigte Stempel, ob die Belohnung bereit ist, sowie Beitritt und letzte Aktivität.
- customer.created: ein Gast ist beigetreten, ohne zusätzliches Feld.
- stamp.added: das Obige plus die Quelle des Stempels (manual, api, auto, survey_reward, kiosk).
- stamp.removed: wie beim Hinzufügen, mit der Quelle der Rücknahme.
- reward.ready: der Gast hat die nötigen Stempel erreicht, ohne zusätzliches Feld.
- reward.redeemed: die Art der Einlösung (staff, manual, auto, api).
- pass.updated: welche Karten auf dem Telefon aktualisiert wurden (apple, google).
- Header: X-Stmpr-Event enthält den Ereignisnamen, X-Stmpr-Delivery die Lieferungs-ID und X-Stmpr-Signature lautet t=Zeitstempel,v1=HMAC-SHA256, signiert mit deinem Signing-Secret.
- Antwort: Wir erwarten eine 2xx innerhalb von 10 Sekunden. Ohne sie versuchen wir es insgesamt fünfmal, mit 10 Sekunden, 1 Minute, 5 Minuten und 15 Minuten Abstand.
Beispielanfrage pro Ereignis
customer.created
{
"event": "customer.created",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 0,
"stamps_required": 10,
"ready_to_redeem": false,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
}
}
}stamp.added
{
"event": "stamp.added",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 7,
"stamps_required": 10,
"ready_to_redeem": false,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
},
"source": "manual"
}
}stamp.removed
{
"event": "stamp.removed",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 6,
"stamps_required": 10,
"ready_to_redeem": false,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
},
"source": "manual"
}
}reward.ready
{
"event": "reward.ready",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 10,
"stamps_required": 10,
"ready_to_redeem": true,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
}
}
}reward.redeemed
{
"event": "reward.redeemed",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 0,
"stamps_required": 10,
"ready_to_redeem": false,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
},
"type": "staff"
}
}pass.updated
{
"event": "pass.updated",
"created_at": "2026-09-01T14:12:03+00:00",
"data": {
"wallet": {
"id": "w_8Kd2Qm",
"name": "Kávé hűségkártya"
},
"customer": {
"id": "c_9YbVt3xQ",
"display_code": "4693",
"stamps_count": 7,
"stamps_required": 10,
"ready_to_redeem": false,
"created_at": "2026-07-14T09:20:11+00:00",
"last_activity_at": "2026-09-01T14:12:03+00:00"
},
"passes": [
"apple",
"google"
]
}
}