Connect-Webhooks
Stripe nutzt Webhooks, um Ihre Anwendung bei einem Ereignis in Ihrem Konto zu benachrichtigen. Alle Connect-Integrationen sollten einen Webhook-Endpoint einrichten, um auf Connect-Ereignisse aufmerksam gemacht zu werden.
Connect-Webhooks
Es gibt einige Arten von Webhooks:
- Account-Webhooks beziehen sich auf Aktivitäten in Ihrem eigenen Konto (zum Beispiel die meisten Anforderungen, die mit Ihren API-Schlüsseln und ohne Authentifizierung als anderes Stripe-Konto erfolgen). Dazu gehören alle Arten von Zahlungen, bis auf solche, die direkt für ein verbundenes Konto erfolgen.
- Connect-Webhooks beziehen sich auf Aktivitäten in einem beliebigen verbundenen Konto. Alle Ereignisse für das verbundene Konto werden an die Connect-Webhooks gesendet. Dazu gehört das wichtige Ereignis
account.updated
für verbundene Konten und Direct Charges.
Achten Sie beim Erstellen darauf, dass Ihr Webhook richtig konfiguriert wird, um Connect-Webhook-Ereignisse empfangen zu können. Diesen Schritt können Sie über die API erledigen, indem Sie den Connect-Parameter beim Erstellen des Webhook-Endpoints auf true
festlegen, oder im Dashboard vornehmen.
Bei Connect-Webhooks ist zu beachten, dass zwar nur Test-Webhooks an Ihre Entwicklungs-Webhook-URLs übermittelt werden, Ihre Produktions-Webhook-URLs aber sowohl Live- als auch Test-Webhooks empfangen werden. Das liegt daran, dass Sie in einer Produktionsanwendung sowohl Live- als auch Test-Transaktionen ausführen können. Wir empfehlen daher, beim Empfang eines Ereignis-Webhooks anhand des Wertes livemode
zu bestimmen, welche Maßnahmen ggf. zu ergreifen sind.
Wie in der Objektreferenz zu Ereignissen angegeben, enthält jedes Ereignis für ein verbundenes Konto auch eine Top-Level-Eigenschaft account
. Sie identifiziert das Konto, an das der Webhook gesendet wird, und das data[object]
, zu dem es gehört. Da diese Objekte zu anderen Konten gehören, müssen Sie die API-Anfragen als das entsprechende verbundene Konto stellen, um auf sie zuzugreifen.
{ "id":
, "livemode": true, "object": "event", "type": "customer.created", "account":"{{EVENT_ID}}", "pending_webhooks": 2, "created": 1349654313, "data": {...} }"{{CONNECTED_ACCOUNT_ID}}"
Es gibt verschiedene Ereignisse im Zusammenhang mit Konten, für die Stripe eine solche Benachrichtigung empfiehlt:
Ereignis | data.object type | Beschreibung |
---|---|---|
account.application.deauthorized | application | Occurs when a connected account disconnects from your platform. You can use it to trigger cleanup on your server. Available for connected accounts with access to the Stripe Dashboard, which includes Standard accounts. |
account.external_account.updated | Ein externes Konto, zum Beispiel card oder bank_account | Tritt auf, wenn ein mit einem verbundenen Konto verbundenes Konto oder eine Debitkarte aktualisiert wird. Dies kann sich auf Auszahlungen auswirken. Verfügbar für verbundene Konten, die von Ihrer Plattform gesteuert werden, einschließlich Custom- und Express-Konten sowie Standard-Konten mit aktivierten Plattformkontrollen. |
account.updated | account | Ermöglicht Ihnen die Überwachung von Veränderungen bei den Anforderungen verbundener Konten sowie von Statusänderungen. Verfügbar für alle verbundenen Konten. |
balance.available | balance | Occurs when your Stripe balance has been updated (for example, when funds you’ve added from your bank account are available for transfer to your connected account). |
payment_intent.succeeded | payment_intent | Occurs when a payment intent results in a successful charge. Available for all payments, including destination and direct charges. |
payout.failed | payout | Occurs when a payout fails. When a payout fails, the external account involved will be disabled, and no automatic or manual payouts can go through until the external account is updated. |
person.updated | person | Wenn Sie die Persons API verwenden, können Sie damit Änderungen an den Anforderungen und Statusänderungen für Einzelpersonen überwachen. Dies ist verfügbar für verbundene Konten, die von Ihrer Plattform gesteuert werden, einschließlich Custom- und Express-Konten sowie Standard-Konten mit aktivierten Plattformkontrollen. |
In der Regel empfehlen wir, dass Connect-Integrationen sich über die oben aufgeführten Ereignisse benachrichtigen lassen. Es gibt aber noch viele weitere Ereignistypen, die für Sie interessant sein könnten.
Webhooks lokal testen
Sie können die Stripe-CLI verwenden, um Webhooks lokal zu testen.
Falls noch nicht vorhanden, installieren Sie die Stripe-CLI auf Ihrem Rechner.
Melden Sie sich in Ihrem Stripe-Konto an und richten Sie die CLI ein, indem Sie in der Befehlszeile
stripe login
ausführen.Lassen Sie Ihren lokalen Host ein simuliertes Ereignis in Ihrem verbundenen Konto empfangen, indem Sie in einem Terminalfenster
stripe listen --forward-to localhost:{PORT}/webhook
und in einem anderenstripe trigger {{EVENT_NAME}}
ausführen.
Notiz
Bei Connect-Webhooks verwenden Sie --forward-connect-to
mit stripe listen
und --stripe-account
mit stripe trigger
.