Loyalty Webhooks

Erhalte Echtzeit-Benachrichtigungen über Loyalty-Events wie Punkte-Vergabe, Einlösungen und Tier-Upgrades direkt an deine Server.

Receive real-time notifications about loyalty events like points earned, redemptions, and tier upgrades directly to your servers.

Basis-Loyalty-Webhooks (loyalty.points_earned, loyalty.points_redeemed etc.) erfordern mindestens das GO-Paket. Tier-Events (loyalty.tier_changed) erfordern PRIME.Basic loyalty webhooks (loyalty.points_earned, loyalty.points_redeemed etc.) require at least the GO package. Tier events (loyalty.tier_changed) require PRIME.

Webhook registrierenRegister Webhook

cURL

curl -X POST \ ".../apiGateway/api/v1/getLoyaltyWebhookEvents" \ -H "Authorization: Bearer $SK" \ -d '{ "storeId": "store_a", "url": "https://yourserver.com/webhooks/loyalty", "events": [ "loyalty.points_earned", "loyalty.points_redeemed", "loyalty.tier_changed", "loyalty.enrollment", "loyalty.reward_unlocked" ], "secret": "whsec_your_hmac_secret" }'

Event-TypenEvent Types

Event	BeschreibungDescription	Wann ausgelöstTrigger
`loyalty.points_earned`	Punkte wurden vergebenPoints were awarded	Nach jedem Einkauf via `addLoyaltyPoints`After every purchase via `addLoyaltyPoints`
`loyalty.points_redeemed`	Punkte wurden eingelöstPoints were redeemed	Bei Einlösung via `redeemLoyaltyPoints`On redemption via `redeemLoyaltyPoints`
`loyalty.tier_changed`	Stufe geändert (Auf- oder Abstieg)Tier changed (upgrade or downgrade)	Wenn Punkte die Schwelle einer neuen Stufe erreichenWhen points reach a new tier threshold
`loyalty.enrollment`	Neuer TeilnehmerNew enrollment	Wenn ein Nutzer dem Programm beitrittWhen a user joins the program
`loyalty.reward_unlocked`	Belohnung freigeschaltetReward unlocked	Wenn ein Nutzer genug Punkte für eine Belohnung hatWhen a user has enough points for a reward

Webhook Payload

JSON

{ "event": "loyalty.points_earned", "timestamp": "2026-03-03T12:30:00.000Z", "data": { "userId": "user_xyz", "programId": "lp_abc123", "storeId": "store_a", "amount": 15, "newBalance": 235, "transactionId": "txn_789" } }

Signatur-VerifizierungSignature Verification

Jeder Webhook enthält einen X-BEEP-Signature-Header. Verifiziere die Signatur mit deinem HMAC-Secret:

Every webhook includes an X-BEEP-Signature header. Verify the signature with your HMAC secret:

Node.js

const crypto = require('crypto'); function verifyWebhookSignature(payload, signature, secret) { const expected = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); }

Webhooks werden maximal 3x wiederholt (nach 1, 5, 30 Minuten). Antworte mit 200 OK innerhalb von 10 Sekunden. Webhooks are retried up to 3x (after 1, 5, 30 minutes). Respond with 200 OK within 10 seconds.

# Webhook registrieren curl -X POST \ ".../api/v1/getLoyaltyWebhookEvents" \ -H "Authorization: Bearer $SK" \ -d '{ "storeId":"store_a", "url":"https://you.com/wh/loyalty", "events":[ "loyalty.points_earned", "loyalty.points_redeemed", "loyalty.tier_changed", "loyalty.enrollment", "loyalty.reward_unlocked" ], "secret":"whsec_your_secret" }' # Signatur-Verifizierung testen echo -n '{"event":"test"}' \ | openssl dgst -sha256 -hmac \ "whsec_your_secret"

const { BeepClient } = require( '@beep_technologies/node' ); const crypto = require('crypto'); const client = new BeepClient( process.env.BEEP_SK ); // Webhook registrieren await client.loyalty.registerWebhook({ storeId: 'store_a', url: 'https://you.com/wh/loyalty', events: [ 'loyalty.points_earned', 'loyalty.points_redeemed', 'loyalty.tier_changed', ], secret: 'whsec_your_secret', }); // Signatur verifizieren function verifySignature( payload, signature, secret ) { const expected = crypto .createHmac('sha256', secret) .update(payload) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected), ); }

import hmac, hashlib from beep import BeepClient client = BeepClient("bk_test_sk_...") # Webhook registrieren client.loyalty.register_webhook( store_id="store_a", url="https://you.com/wh/loyalty", events=[ "loyalty.points_earned", "loyalty.points_redeemed", "loyalty.tier_changed", ], secret="whsec_your_secret", ) # Signatur verifizieren def verify_signature( payload, signature, secret ): expected = hmac.new( secret.encode(), payload.encode(), hashlib.sha256, ).hexdigest() return hmac.compare_digest( signature, expected )

import 'dart:convert'; import 'package:beep_sdk/beep_sdk.dart'; import 'package:crypto/crypto.dart'; final client = BeepClient('bk_test_sk_...'); // Webhook registrieren await client.loyalty.registerWebhook( storeId: 'store_a', url: 'https://you.com/wh/loyalty', events: [ 'loyalty.points_earned', 'loyalty.points_redeemed', 'loyalty.tier_changed', ], secret: 'whsec_your_secret', ); // Signatur verifizieren bool verifySignature( String payload, String sig, String secret, ) { final hmac = Hmac(sha256, utf8.encode(secret)); final expected = hmac .convert(utf8.encode(payload)) .toString(); return sig == expected; }