Stripe-Zahlungsbenachrichtigungen: eine Push-Benachrichtigung für jeden Verkauf, jede fehlgeschlagene Zahlung und jeden Streitfall

Der erste Verkauf des Tages ist der, von dem du erfahren willst. Die fehlgeschlagene Verlängerung um 2 Uhr nachts wiegt schwerer, und ein Streitfall hat eine Frist: Reagierst du nicht rechtzeitig, verlierst du ihn. Stripe weiß von allen dreien in dem Moment, in dem sie passieren. Du erfährst es, wenn du das Dashboard das nächste Mal öffnest.
Stripe hat eigene Benachrichtigungen. Die Stripe-Dashboard-App für iOS und Android kann Push-Benachrichtigungen für neue Zahlungen, neue Kunden, strittige Zahlungen, ausgezahlte Überweisungen und eine tägliche Zusammenfassung schicken, und das Dashboard kann dir per E-Mail von Kontoereignissen berichten. Das deckt viel ab. Was es dir nicht gibt, ist Kontrolle: Du kannst den Wortlaut nicht wählen, eine fehlgeschlagene Rechnung nicht lauter machen als einen Verkauf und nichts aus deinen eigenen Systemen in denselben Kanal leiten. Ein Webhook von Stripe zu Pocket Alert kann das.
Was du brauchst
- Ein Stripe-Konto mit der Berechtigung, Webhooks anzulegen (Rolle Administrator oder Developer).
- Ein Pocket-Alert-Konto, einen API-Schlüssel von API-Schlüssel und die App auf deinem iPhone oder Android-Handy.
- Für den Code-Weg: Node 20 oder neuer und einen öffentlich erreichbaren Ort, an dem es läuft.
Stufe 1: ohne Code
Stripe schickt jedes Ereignis als JSON, und Pocket-Alert-Webhooks nehmen JSON entgegen und rendern es über eine Vorlage. Mehr Infrastruktur braucht es dafür nicht.
1. Einen Pocket-Alert-Webhook pro Ereignistyp anlegen
Der Trick: ein Webhook pro Ereignisart. Der Push-Titel lautet immer Webhook <name>, der Name bestimmt also, was auf dem Sperrbildschirm steht, und jeder Webhook hat eigene Standardpriorität und eigene Buttons. Der kostenlose Tarif enthält einen Webhook, fang also mit Verkäufen an. Alle vier brauchst du einen bezahlten Tarif, der auch die Buttons freischaltet.
Webhooks legst du in der Konsole unter Webhooks an. Dort legst du Name, Vorlage und Standardpriorität fest. Aktionsbuttons werden über die API gesetzt, am schnellsten holst du also alles auf einmal mit einem curl-Aufruf pro Webhook:
export PA_KEY='YOUR_API_KEY'
curl -sS https://api.pocketalert.app/v1/webhooks \
-H "Token: $PA_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- <<'EOF'
{
"name": "Stripe sale",
"message": "%data.object.amount_total% %data.object.currency% from %data.object.customer_details.email% (%data.object.payment_status%)",
"default_level": 0,
"actions": "[{\"type\":\"view\",\"label\":\"Open in Stripe\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
EOF
Die Antwort enthält einen url-Slug. Deine Empfangs-URL lautet https://p4a.me/wh/<slug>, die Konsole zeigt sie ebenfalls an. actions ist ein JSON-String und kein Array, deshalb sind die Anführungszeichen escaped.
Wiederhole das mit diesen Bodies für die anderen drei:
{
"name": "Stripe payment failed",
"message": "%data.object.amount_due% %data.object.currency% failed for %data.object.customer_email%, attempt %data.object.attempt_count%",
"default_level": 1,
"actions": "[{\"type\":\"view\",\"label\":\"Open invoice\",\"value\":\"https://dashboard.stripe.com/invoices/%data.object.id%\"},{\"type\":\"copy\",\"label\":\"Copy pay link\",\"value\":\"%data.object.hosted_invoice_url%\"}]"
}
{
"name": "Stripe dispute",
"message": "%data.object.amount% %data.object.currency% disputed. Reason: %data.object.reason%",
"default_level": 2,
"actions": "[{\"type\":\"view\",\"label\":\"Open payment\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
{
"name": "Stripe subscription",
"message": "New %data.object.status% subscription: %data.object.items.data.0.price.unit_amount% %data.object.currency% per %data.object.items.data.0.price.recurring.interval%",
"default_level": -1,
"actions": "[{\"type\":\"view\",\"label\":\"Open subscription\",\"value\":\"https://dashboard.stripe.com/subscriptions/%data.object.id%\"}]"
}
Die Stufen reichen von -2 (lautlos) bis 2 (kritisch). Eine fehlgeschlagene Zahlung ist high und kommt auf dem iPhone durch den Fokus. Ein Streitfall ist critical und spielt auch bei stummgeschaltetem Schalter und bei Nicht stören einen Ton ab. Kritische Benachrichtigungen brauchen einen bezahlten Tarif; im kostenlosen Tarif kommen sie als high an. Neue Abos sind low: gut zu wissen, aber kein Grund zu vibrieren.
Der Kopieren-Button auf dem Push für fehlgeschlagene Zahlungen legt die gehostete Zahlungsseite der Rechnung in deine Zwischenablage, bereit zum Einfügen in eine E-Mail mit „Deine Karte wurde abgelehnt“.
2. Event-Ziele in Stripe anlegen
Öffne im Stripe-Dashboard die Workbench, wechsle zum Tab Webhooks und klicke auf Create an event destination. Dann:
- Wähle Your account.
- Wähle die Payload Snapshot. Stripe empfiehlt für neuen Code inzwischen Thin, aber ein Thin-Ereignis enthält nur die Objekt-ID, und dann hat eine Vorlage keinen Betrag und keine E-Mail zum Anzeigen. Snapshot schickt das vollständige Objekt.
- Wähle das Ereignis, zum Beispiel
checkout.session.completed. - Wähle als Zieltyp Webhook endpoint und füge die passende
https://p4a.me/wh/...-URL ein.
Mach das einmal pro Pocket-Alert-Webhook, sodass jedes Stripe-Ziel genau einen Ereignistyp an genau eine URL schickt:
| Stripe-Ereignis | Pocket-Alert-Webhook | Push-Titel | Stufe |
|---|---|---|---|
checkout.session.completed | Stripe sale | Webhook Stripe sale | Standard |
invoice.payment_failed | Stripe payment failed | Webhook Stripe payment failed | Hoch |
charge.dispute.created | Stripe dispute | Webhook Stripe dispute | Kritisch |
customer.subscription.created | Stripe subscription | Webhook Stripe subscription | Niedrig |
Stripe erlaubt 16 Event-Ziele pro Konto, vier sind also kein Problem.
Checkout oder PaymentIntents? Wenn Kunden über Checkout oder Payment Links zahlen, nimm checkout.session.completed. Wenn du ein eigenes Zahlungsformular baust, nimm stattdessen payment_intent.succeeded und ändere die Vorlage auf %data.object.amount% %data.object.currency% %data.object.receipt_email% und den Button auf /payments/%data.object.id%. Beide Ereignisse zu abonnieren ergibt zwei Pushes pro Verkauf, weil eine Checkout-Zahlung beide Ereignisse auslöst.
3. Testen
Lege eine Testzahlung in einer Sandbox an oder führe stripe trigger checkout.session.completed mit der Stripe CLI aus. Öffne dann den Webhook in der Pocket-Alert-Konsole: Sein Verlauf zeigt jede Anfrage, die Stripe geschickt hat, mit Headern, Rohbody, gerenderter Nachricht und Antwortstatus. Wenn ein Feld leer bleibt, siehst du dort, welcher Pfad falsch war.
Ein Verkauf kommt so an:
Webhook Stripe sale
4900 usd from [email protected] (paid)
[Open in Stripe]
Was die Vorlage nicht kann
Kenn die Grenzen, bevor du dich darauf verlässt:
- Beträge sind in der kleinsten Währungseinheit. Stripe schickt
4900für 49,00 $ und5000für ¥5.000, weil der Yen keine Cent kennt. Die Vorlage übernimmt Werte unverändert und kann nicht durch 100 teilen.4900 usdliest du schnell, aber wenn du$49.00willst, brauchst du Stufe 2. - Keine Signaturprüfung. Stripe signiert jede Anfrage mit einem
Stripe-Signature-Header. Pocket Alert prüft Signaturen von Drittanbietern nicht; der zufällige Slug in der URL ist das einzige Geheimnis. Wer ihn kennt, kann dir gefälschte „Verkäufe“ schicken. Für eine Benachrichtigung ist das eher lästig als gefährlich, weil nichts ausgeliefert wird. Halte die URL trotzdem privat, und nimm Stufe 2, wenn du belegen willst, dass ein Push von Stripe kam. - Keine Bedingungen. Eine Vorlage kann nicht sagen „nur Verkäufe über 500 $ melden“ oder „Testmodus überspringen“. Filtern geschieht bei Stripe über die Ereignisse, die du auswählst, oder im Code.
- Dashboard-Buttons zeigen auf den Livemodus. Testobjekte liegen unter
dashboard.stripe.com/test/.... Bei einem Testmodus-Ereignis öffnet der Button also eine Seite, die es nicht gibt. Streitfälle aus der alten Charges-API haben keinepayment_intent, dann bleibt der Button ohne Ziel. - Abos zeigen nur den ersten Preis.
items.data.0ist die erste Position. Das Ereignis enthält eine Kunden-ID, keine E-Mail. - Jedes Ereignis zählt zu deinem Tageskontingent. Der kostenlose Tarif hat 50 Nachrichten am Tag. Darüber antwortet Pocket Alert mit
429, und Stripe wertet das als fehlgeschlagene Zustellung und wiederholt sie im Livemodus bis zu drei Tage lang.
Stufe 2: ein kleiner, geprüfter Handler
Wenn du echte Währungsformatierung, Signaturprüfung und einen Endpunkt für alle Ereignisse willst, setze etwa sechzig Zeilen Node zwischen Stripe und Pocket Alert. Er nutzt die offizielle Stripe-Bibliothek, um die Signatur zu prüfen, und POST /v1/messages, um den Push zu senden.
npm install express stripe
// server.mjs
import express from 'express';
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();
function money(minor, currency) {
const fmt = new Intl.NumberFormat('en-US', { style: 'currency', currency: currency.toUpperCase() });
return fmt.format(minor / 10 ** fmt.resolvedOptions().maximumFractionDigits);
}
function toPush(event) {
const o = event.data.object;
switch (event.type) {
case 'checkout.session.completed':
return { title: `Sale ${money(o.amount_total, o.currency)}`, level: 'default',
message: `${o.customer_details?.email ?? 'no email'} · ${o.payment_status}`,
path: o.payment_intent ? `payments/${o.payment_intent}` : `customers/${o.customer}` };
case 'invoice.payment_failed':
return { title: `Payment failed ${money(o.amount_due, o.currency)}`, level: 'high',
message: `${o.customer_email ?? o.customer} · attempt ${o.attempt_count}`,
path: `invoices/${o.id}` };
case 'charge.dispute.created':
return { title: `Dispute ${money(o.amount, o.currency)}`, level: 'critical',
message: `Reason: ${o.reason}. Evidence due ${new Date(o.evidence_details.due_by * 1000).toDateString()}`,
path: `payments/${o.payment_intent ?? o.charge}` };
case 'customer.subscription.created': {
const price = o.items.data[0]?.price;
return { title: 'New subscription', level: 'low',
message: price?.unit_amount != null
? `${money(price.unit_amount, price.currency)} per ${price.recurring?.interval} · ${o.status}`
: o.status,
path: `subscriptions/${o.id}` };
}
}
return null;
}
app.post('/stripe-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
let event;
try {
event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
} catch (err) {
return res.status(400).send(`Bad signature: ${err.message}`);
}
res.sendStatus(200);
const push = toPush(event);
if (!push) return;
const dashboard = event.livemode ? 'https://dashboard.stripe.com/' : 'https://dashboard.stripe.com/test/';
await fetch('https://api.pocketalert.app/v1/messages', {
method: 'POST',
headers: { Token: process.env.POCKETALERT_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({
title: push.title,
message: push.message,
level: push.level,
actions: [{ type: 'view', label: 'Open in Stripe', value: dashboard + push.path }],
}),
}).catch((err) => console.error('Pocket Alert:', err.message));
});
app.listen(process.env.PORT ?? 4242);
STRIPE_SECRET_KEY=sk_live_... STRIPE_WEBHOOK_SECRET=whsec_... POCKETALERT_KEY=... node server.mjs
Die wichtigen Details:
express.rawhält den Body als Bytes.constructEventbraucht die Anfrage genau so, wie Stripe sie geschickt hat, und ein JSON-Parser würde die Signatur zerstören. Außerdem lehnt er Ereignisse ab, die älter als fünf Minuten sind, das verhindert Replay-Angriffe.- Der Handler antwortet mit
200, bevor er Pocket Alert aufruft, weil Stripe eine schnelle2xx-Antwort erwartet. FürSTRIPE_SECRET_KEYreicht ein eingeschränkter Schlüssel mit Leserechten; dieser Code ruft die Stripe-API nie auf. Intl.NumberFormatkennt die Nachkommastellen jeder Währung, daher wird4900 usdzu$49.00und5000 jpyzu¥5,000.- Das Flag
livemodewählt den richtigen Dashboard-Pfad, sodass Testereignisse Seiten im Testmodus öffnen.
Lege in Stripe ein Event-Ziel mit der Payload Snapshot, allen vier Ereignissen und der URL deines Servers an und kopiere danach das Signiergeheimnis whsec_ von der Zielseite. Zum lokalen Testen gibt stripe listen --forward-to localhost:4242/stripe-webhook ein Geheimnis aus, und stripe trigger invoice.payment_failed schickt ein signiertes Testereignis.
Auf deinem Handy erscheint dann ein Push mit dem Titel „Sale $49.00“ und „[email protected] · paid“ darunter, und ein Streitfall weckt dich mit der Frist im Text.
Willst du Verkauf und Anmeldung im selben Feed? Schick deine Anmeldeformulare mit Anmeldungs-Benachrichtigungen an dieselbe App, dann lesen sich die beiden wie ein Funnel.
Wenn nichts ankommt
- Schau zuerst bei Stripe nach. Öffne das Ziel in der Workbench und prüfe den Tab Event deliveries. Ein
400mit „Invalid JSON“ heißt, dass etwas anderes als Stripe-JSON die URL erreicht hat. Ein429heißt, dass du das Tageslimit erreicht hast. - Dann der Verlauf des Pocket-Alert-Webhooks. Ist die Anfrage dort, aber die Nachricht stellenweise leer, existiert ein Vorlagenpfad in diesem Ereignis nicht. Kopiere den Body aus dem Verlauf und prüfe die Feldnamen.
- Versehentlich Thin. Zeigt der Push leere Beträge und enthält der Verlaufs-Body
related_objectstattdata, wurde das Ziel als Thin angelegt. Lege ein neues mit Snapshot an. - Signaturfehler in Stufe 2. Jedes Ziel hat ein eigenes
whsec_-Geheimnis, und ein Sandbox-Geheimnis unterscheidet sich vom Livemodus-Geheimnis. Achte außerdem darauf, dass nichts davor, etwa ein Proxy oder eine Framework-Middleware, den Body neu kodiert.
FAQ
Ersetzt das die Stripe-Dashboard-App?
Nein, und das muss es auch nicht. Die Stripe-App ist der Ort, um zu erstatten, einen Kunden nachzuschlagen oder dein Guthaben zu prüfen. Pocket Alert liefert dir die Benachrichtigung selbst: deinen Wortlaut, deine Prioritätsstufen und Buttons, in einem Feed zusammen mit den übrigen Meldungen von Servern, CI und Formularen.
Welche Ereignisse sind einen Push wert?
Fang mit den vier oben an. invoice.paid ist ein guter Zusatz für SaaS-Verlängerungen, und customer.subscription.deleted informiert dich über Kündigungen. Stripe empfiehlt, nur die Ereignisse zu abonnieren, die du nutzt, das hält auch dein Handy ruhig.
Kann ich einen Push pro Tag statt einen pro Verkauf bekommen?
Nicht über den Webhook. Setze die Stufe des Verkauf-Webhooks auf silent, dann sammeln sich Verkäufe im Feed, ohne Ton. high und critical behältst du für Ereignisse, die dich wirklich brauchen.
Ist es kostenlos?
Stripe-Webhooks kosten nichts. Der kostenlose Tarif von Pocket Alert deckt 50 Nachrichten am Tag auf einem Gerät ab, für einen kleinen Shop reicht das. Kritische Benachrichtigungen, die Nicht stören überschreiben, gibt es in den bezahlten Tarifen.
Kostenloses Konto erstellen, eine URL in Stripe einfügen, und der nächste Verkauf landet auf deinem Handy.