WebhooksWebhooks
BEEP! sendet HTTP POST-Requests an deine URL, wenn relevante Events in deinen Stores passieren, in Echtzeit. Alle 11 Event-Typen sind hier dokumentiert.
BEEP! sends HTTP POST requests to your URL when relevant events occur in your stores, in real time. All 11 event types are documented here.
ÜbersichtOverview
| Event | Trigger | Tier |
|---|
| checkout.completed |
Kunde hat erfolgreich bezahlt |
GROW |
| checkout.started |
Checkout-Prozess begonnen |
GROW |
| checkout.cancelled |
Checkout abgebrochen oder Timeout |
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 |
GROW |
| clickcollect.picked_up |
Bestellung wurde abgeholt |
GROW |
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 !== `sha256=${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 |
sha256={hex} |
sha256=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 Stripe-Checkout erfolgreich abgeschlossen wird und der Zahlungseingang bestätigt ist.
Fired when a Stripe 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": 437,
"currency": "EUR",
"itemCount": 3,
"items": [
{
"name": "Bionade Holunder 0,5L",
"ean": "4104420044052",
"priceUnit": 129,
"quantity": 2,
"vat": 7
}
],
"receiptUrl": "https://beep-c6786.web.app/receipt/txn_mP4kR9nX",
"stripeSessionId": "cs_live_...",
"status": "SUCCESS",
"completedAt": 1740645720000
}
}
checkout.started
GROW
Kunde hat den Checkout eingeleitet (Stripe Checkout Page geöffnet). Zahlungseingang noch nicht bestätigt.
Customer has initiated checkout (Stripe 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.stripe.com/pay/cs_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": "Bionade zum Sparpreis",
"productEan": "4104420044052",
"discountPrice": 0.99,
"originalPrice": 1.29,
"discountPercent": 23,
"scope": "LOCAL",
"validFrom": "2026-03-01T00:00:00.000Z",
"validUntil": "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": "Bionade zum Sparpreis",
"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
GROW
{
"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
GROW
{
"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"
}
}
