WebhooksWebhooks
Echtzeit-Events per HTTP POST. 26 Event-Typen, HMAC-signiert.
Real-time events via HTTP POST. 26 event types, HMAC-signed.
ÜbersichtOverview
| Event |
Trigger |
Tier |
| checkout.completed |
Kunde hat erfolgreich bezahlt |
GROW |
| checkout.started |
Checkout-Prozess begonnen |
GROW |
| checkout.cancelled |
Checkout abgebrochen oder Timeout |
GROW |
| securityTag.deactivated |
Sicherungen deaktiviertSecurity tags deactivated |
GROW |
| offer.published |
Angebot wurde aktiviert |
GO |
| offer.expired |
Angebot ist abgelaufen |
GO |
| offer.clicked |
Nutzer hat ein Angebot geöffnet |
GO |
| store.checkin |
Kunde hat eingecheckt |
GROW |
| store.followed |
Neuer Follower für den Store |
DISCOVER |
| dm.received |
Direkt-Nachricht von einem Kunden |
GO |
| clickcollect.order |
Neue Click & Collect Bestellung |
GO |
| clickcollect.picked_up |
Bestellung wurde abgeholt |
GO |
| product.created |
Neues Produkt via API angelegt |
DISCOVER |
| product.bulk_imported |
Bulk-Import abgeschlossen |
DISCOVER |
| integration.pos.synced |
POS-Sync abgeschlossen |
GROW |
| integration.pos.pushed |
Daten an POS gepusht |
GROW |
| integration.erp.synced |
ERP-Sync abgeschlossen |
GROW |
| integration.erp.pushed |
Daten an ERP gepusht |
GROW |
| integration.psp.configured |
PSP konfiguriert |
GROW |
| payment.created |
Zahlung initiiert |
GROW |
| payment.refunded |
Erstattung initiiert |
GROW |
| loyalty.points_earned |
Punkte gutgeschriebenPoints
earned |
GO |
| loyalty.points_redeemed |
Punkte eingelöstPoints
redeemed |
GO |
| loyalty.checkin_earned |
Punkte via GPS Check-inPoints via GPS check-in |
GO |
| loyalty.qr_earned |
Punkte via QR-Code ScanPoints via QR code scan |
GO |
| loyalty.tier_changed |
Tier-Level geändertTier
level changed |
PRIME |
| loyalty.external_synced |
Externe Loyalty synchronisiertExternal loyalty synced |
PRIME |
Webhook-Endpoint einrichtenSet
Up Webhook Endpoint
Konfiguriere deine Webhook-URL im Developer Dashboard. Du kannst mehrere Endpoints registrieren und pro Endpoint
auswählen, welche Event-Typen geliefert werden sollen.
Configure your webhook URL in the Developer Dashboard. You can register multiple endpoints and choose which event types
each endpoint receives.
import express from
'express';
import crypto from 'crypto';
const app = express();
app.post('/webhooks/beep', express.raw({type: 'application/json'}),
(req, res) => {
const signature = req.headers['x-beep-signature'];
const expectedSig = crypto
.createHmac('sha256', process.env.BEEP_WEBHOOK_SECRET)
.update(req.body)
.digest('hex');
if (signature !== expectedSig) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body);
switch (event.type) {
case 'checkout.completed':
handleCheckoutCompleted(event.data);
break;
case 'offer.clicked':
handleOfferClicked(event.data);
break;
}
res.status(200).json({ received: true });
});
Signatur-VerifikationSignature Verification
Jeder Webhook-Request enthält den Header x-beep-signature mit einem HMAC-SHA256-Hash des Request-Bodys. Verifiziere
diesen Hash, bevor du Events verarbeitest.
Every webhook request contains the header x-beep-signature with an HMAC-SHA256 hash of the request body. Verify this
hash before processing events.
| Header |
Format |
Beispiel |
| x-beep-signature |
{hex} |
7d38cdd... |
| x-beep-event |
string |
checkout.completed |
| x-beep-delivery-id |
uuid |
wh_del_abc123 |
| x-beep-timestamp |
unix ms |
1740645720000 |
Raw Body verwenden!: Für die Signatur-Verifikation muss der rohe, unveränderliche
Request-Body (als Buffer) gehashed werden. Nicht der geparste JSON-String. In Express: express.raw() statt express.json().
Delivery & Retry-LogikDelivery & Retry Logic
+2 Std
4. (letzter) Versuch
BEEP! betrachtet eine Delivery als erfolgreich, wenn dein Server einen 2xx-Statuscode innerhalb von 5 Sekunden zurückgibt. Bei Timeout oder Non-2xx
wird nach obigem Schema wiederholt. Alle Delivery-Versuche sind im Dashboard einsehbar.
BEEP! considers a delivery successful when your server returns a 2xx status code within 5 seconds. On timeout or non-2xx it retries according
to the schedule above. All delivery attempts are visible in the Dashboard.
Idempotenz: Dieselbe Delivery-ID (x-beep-delivery-id)
kann bei Retries erneut auftreten. Speichere verarbeitete Delivery-IDs und gib bei Duplikaten trotzdem 200 zurück.
checkout.completed
GROW
Wird ausgelöst, wenn ein Checkout erfolgreich abgeschlossen wird und der
Zahlungseingang bestätigt ist.
Fired when a checkout is successfully completed and payment receipt is confirmed.
{
"id": "evt_bk_JqKp3nLaM7",
"type": "checkout.completed",
"created": 1740645720000,
"livemode": true,
"apiVersion": "2026-01",
"data": {
"object": "purchase",
"id": "txn_mP4kR9nX",
"sessionId": "sess_k7aB3xQm9wPz",
"storeId": "store_abc123",
"storeName": "Frische Ecke Mitte",
"userId": "usr_42",
"totalCent": 417,
"currency": "EUR",
"itemCount": 3,
"items": [
{
"name": "Bio-Vollmilch 3,5%",
"ean": "4000000000001",
"priceUnit": 149,
"quantity": 2,
"vat": 7
}
],
"receiptUrl": "https://beep-c6786.web.app/receipt/txn_mP4kR9nX",
"checkoutSessionId": "cs_live_...",
"status": "SUCCESS",
"completedAt": 1740645720000,
"securityTagMode": "manual",
"securityTagStatus": "pending"
}
}
securityTag.deactivated
GROW
Wird ausgelöst, wenn Produktsicherungen für einen Scan & Go Kauf erfolgreich deaktiviert oder entfernt wurden (via Station oder RFID).
Fired when security tags for a Scan & Go purchase have been successfully deactivated or removed (via station or RFID).
{
"id": "evt_st_Rm3Xp5kN7z",
"type": "securityTag.deactivated",
"created": 1740645780000,
"livemode": true,
"data": {
"purchaseId": "txn_mP4kR9nX",
"storeId": "store_abc123",
"method": "station",
"deactivatedItems": ["4000000000001"],
"deactivatedAt": 1740645780000
}
}
checkout.started
GROW
Kunde hat den Checkout eingeleitet (Checkout-Seite geöffnet). Zahlungseingang noch
nicht bestätigt.
Customer has initiated checkout (checkout page opened). Payment receipt not yet
confirmed.
{
"id": "evt_bk_BqPp0mXaL3",
"type": "checkout.started",
"created": 1740645680000,
"livemode": true,
"data": {
"object": "purchase",
"id": "txn_mP4kR9nX",
"sessionId": "sess_k7aB3xQm9wPz",
"storeId": "store_abc123",
"itemCount": 3,
"totalCent": 437,
"currency": "EUR",
"checkoutUrl": "https://checkout.example.com/pay/session_live_...",
"status": "PENDING_PAYMENT"
}
}
checkout.cancelled
GROW
Checkout wurde abgebrochen (Nutzer verlässt Checkout-Page) oder ist nach 30 Minuten
abgelaufen.
Checkout was cancelled (user leaves checkout page) or expired after 30 minutes.
{
"id": "evt_bk_CnQq1oYbM4",
"type": "checkout.cancelled",
"created": 1740647280000,
"livemode": true,
"data": {
"object": "purchase",
"id": "txn_mP4kR9nX",
"sessionId": "sess_k7aB3xQm9wPz",
"storeId": "store_abc123",
"totalCent": 437,
"reason": "user_abandoned",
"status": "CANCELLED"
}
}
offer.published
GO
{
"id": "evt_bk_DoPr2pZcN5",
"type": "offer.published",
"created": 1740600000000,
"data": {
"object": "offer",
"offerId": "off_xyz789",
"storeId": "store_abc123",
"title": "Bio-Vollmilch Sonderangebot",
"productEan": "4000000000001",
"discountPrice": 1.19,
"originalPrice": 1.49,
"discountPercent": 20,
"scope": "LOCAL",
"validFrom": "2026-03-01T00:00:00.000Z",
"validTo": "2026-03-07T23:59:59.000Z",
"status": "ACTIVE"
}
}
offer.expired
GO
{
"id": "evt_bk_EpQs3qAdO6",
"type": "offer.expired",
"created": 1740945599000,
"data": {
"object": "offer",
"offerId": "off_xyz789",
"storeId": "store_abc123",
"title": "Bio-Vollmilch Sonderangebot",
"totalClicks": 342,
"totalFavorites": 89,
"status": "EXPIRED"
}
}
offer.clicked
GO
{
"id": "evt_bk_FqRt4rBeP7",
"type": "offer.clicked",
"created": 1740700000000,
"data": {
"object": "offer",
"offerId": "off_xyz789",
"storeId": "store_abc123",
"totalClicks": 128
}
}
store.checkin
GROW
{
"id": "evt_bk_GrSu5sCfQ8",
"type": "store.checkin",
"created": 1740645640000,
"data": {
"object": "session",
"sessionId": "sess_k7aB3xQm9wPz",
"storeId": "store_abc123",
"userId": "usr_42",
"checkedInAt": 1740645640000,
"estimatedItems": null
}
}
store.followed
DISCOVER
{
"id": "evt_bk_HsTv6tDgR9",
"type": "store.followed",
"created": 1740700000000,
"data": {
"object": "follow",
"storeId": "store_abc123",
"userId": "usr_77",
"totalFollowers": 848
}
}
dm.received
GO
{
"id": "evt_bk_ItUw7uEhS0",
"type": "dm.received",
"created": 1740720000000,
"data": {
"object": "message",
"messageId": "msg_abc456",
"storeId": "store_abc123",
"senderId": "usr_99",
"preview": "Habt ihr noch die Bio-Eier?...",
"sentAt": 1740720000000
}
}
clickcollect.order
GO
{
"id": "evt_bk_JuVx8vFiT1",
"type": "clickcollect.order",
"created": 1740750000000,
"data": {
"object": "order",
"orderId": "ord_xyz123",
"storeId": "store_abc123",
"userId": "usr_42",
"items": [
{
"name": "Bio-Eier 10er",
"ean": "4005999134741",
"quantity": 2,
"priceUnit": 349,
"vat": 7
}
],
"totalCent": 698,
"currency": "EUR",
"pickupSlot": "2026-03-01T14:00:00.000Z",
"status": "CONFIRMED"
}
}
clickcollect.picked_up
GO
{
"id": "evt_bk_KvWy9wGjU2",
"type": "clickcollect.picked_up",
"created": 1740754000000,
"data": {
"object": "order",
"orderId": "ord_xyz123",
"storeId": "store_abc123",
"userId": "usr_42",
"pickedUpAt": 1740754000000,
"status": "PICKED_UP"
}
}
product.created
DISCOVER
Wird ausgelöst, wenn ein neues Produkt via API angelegt wird (insertProduct).
Fired when a new product is created via API (insertProduct).
{
"id": "evt_bk_LwXz0xHkV3",
"type": "product.created",
"created": 1740800000000,
"livemode": true,
"data": {
"object": "product",
"productId": "prod_abc123",
"ean": "4000000000001",
"name": "Bio-Vollmilch 3,5%",
"brand": "BioHof",
"price": 1.49,
"vat": 7,
"category": "Molkerei",
"storeId": "store_abc123"
}
}
product.bulk_imported
DISCOVER
Wird ausgelöst, wenn ein Bulk-Import abgeschlossen ist (bulkImportProducts).
Fired when a bulk product import completes (bulkImportProducts).
{
"id": "evt_bk_MxYa1yIlW4",
"type": "product.bulk_imported",
"created": 1740801000000,
"livemode": true,
"data": {
"object": "import",
"storeId": "store_abc123",
"importedCount": 142,
"updatedCount": 37,
"skippedCount": 3,
"status": "COMPLETED"
}
}
integration.pos.synced
GROW
POS-Katalog-Sync erfolgreich abgeschlossen (syncPOS).
POS catalogue sync completed successfully (syncPOS).
{
"id": "evt_bk_NyZb2zJmX5",
"type": "integration.pos.synced",
"created": 1740810000000,
"livemode": true,
"data": {
"object": "integration",
"storeId": "store_abc123",
"provider": "korona",
"syncedProducts": 315,
"updatedProducts": 12,
"status": "SUCCESS",
"completedAt": 1740810000000
}
}
integration.pos.pushed
GROW
Transaktionsdaten wurden erfolgreich ins POS-System zurückgespielt (pushToPOS).
Transaction data successfully pushed back to the POS system (pushToPOS).
{
"id": "evt_bk_OzAc3aKnY6",
"type": "integration.pos.pushed",
"created": 1740811000000,
"livemode": true,
"data": {
"object": "integration",
"storeId": "store_abc123",
"provider": "korona",
"pushedTransactions": 8,
"status": "SUCCESS"
}
}
integration.erp.synced
GROW
ERP-Sync erfolgreich abgeschlossen (syncERP).
ERP sync completed successfully (syncERP).
{
"id": "evt_bk_PaBd4bLoZ7",
"type": "integration.erp.synced",
"created": 1740820000000,
"livemode": true,
"data": {
"object": "integration",
"storeId": "store_abc123",
"provider": "lexoffice",
"syncedEntries": 47,
"status": "SUCCESS"
}
}
integration.erp.pushed
GROW
Transaktionsdaten wurden erfolgreich ins ERP-System zurückgespielt (pushToERP).
Transaction data successfully pushed back to the ERP system (pushToERP).
{
"id": "evt_bk_QbCe5cMpA8",
"type": "integration.erp.pushed",
"created": 1740821000000,
"livemode": true,
"data": {
"object": "integration",
"storeId": "store_abc123",
"provider": "lexoffice",
"pushedEntries": 23,
"status": "SUCCESS"
}
}
GROW
Ein PSP (Zahlungsanbieter) wurde erfolgreich konfiguriert (configurePSP).
A payment service provider was successfully configured (configurePSP).
{
"id": "evt_bk_RcDf6dNqB9",
"type": "integration.psp.configured",
"created": 1740830000000,
"livemode": true,
"data": {
"object": "integration",
"storeId": "store_abc123",
"provider": "stripe",
"status": "ACTIVE",
"configuredAt": 1740830000000
}
}
payment.created
GROW
Eine Zahlung wurde über den konfigurierten PSP initiiert (processPayment).
A payment was initiated via the configured PSP (processPayment).
{
"id": "evt_bk_SdEg7eOrC0",
"type": "payment.created",
"created": 1740840000000,
"livemode": true,
"data": {
"object": "payment",
"paymentId": "pay_abc789",
"storeId": "store_abc123",
"amountCent": 2499,
"currency": "EUR",
"provider": "stripe",
"status": "PENDING"
}
}
payment.refunded
GROW
Eine Erstattung wurde über den konfigurierten PSP initiiert (refundPayment).
A refund was initiated via the configured PSP (refundPayment).
{
"id": "evt_bk_TeEh8fPsD1",
"type": "payment.refunded",
"created": 1740841000000,
"livemode": true,
"data": {
"object": "payment",
"paymentId": "pay_abc789",
"refundId": "ref_xyz456",
"storeId": "store_abc123",
"refundedCent": 2499,
"currency": "EUR",
"provider": "stripe",
"status": "REFUNDED"
}
}
Mehr erkundenExplore more
