Traitez les webhooks entrants avec des gestionnaires de notifications d’événements.Version bêta publique

Écrivez une fonction qui s’exécute lorsqu’aucun rappel dédié n’a été enregistré pour un type d’événement donné. Elle recevra la EventNotification, ainsi qu’un StripeClient et des informations supplémentaires sur l’événement.

Cette fonction peut enregistrer la réception d’un événement inattendu ou déclencher une erreur afin de vous signaler un état imprévu. Vous pouvez également ajouter une logique métier dans cette fonction si vous traitez des événements pour lesquels votre SDK ne fournit pas de types.

def fallback_callback(notif: EventNotification, client: StripeClient, details: UnhandledNotificationDetails):
    print(f'Got an unhandled event of type {notif.type}!')

Lors de votre migration, il est conseillé de regrouper tout le code de votre endpoint de webhook dans cette fonction. Vous pourrez ensuite transférer chaque type d’événement vers sa propre fonction.

Dans votre endpoint de webhook, initialisez un EventNotificationHandler en fournissant votre rappel de secours. StripeClient propose une méthode pratique pour simplifier cette étape.

client = StripeClient(api_key)
handler = client.notification_handler(webhook_secret, fallback_callback)

Créez ensuite une fonction dédiée au traitement d’un type d’événement particulier. Elle exploite les types d’événements introduits avec la version de l’API Clover de septembre 2025.

Votre rappel recevra la notification d’événement convertie dans la classe appropriée. Vous disposerez également d’un StripeClient lié au contexte de la notification, ce qui facilite la réalisation d’appels à l’API supplémentaires sans avoir à gérer les identifiants de compte.

# can be anywhere in your codebase
@handler.on_v1_billing_meter_error_report_triggered
def handle_meter_error(
    notif: V1BillingMeterErrorReportTriggeredEventNotification,
    client: StripeClient,
):
    event = notif.fetch_event()
    print(f"Err! No meter found: {event.data.developer_message_summary}")

Il est possible d’enregistrer aucun ou plusieurs rappels. Si aucun n’est enregistré, tous les événements seront redirigés vers votre rappel de secours.

Envoyez les corps POST entrants vers le gestionnaire. Cela remplace la majeure partie du code original de votre endpoint de webhook.

@app.route("/webhook", methods=["POST"])
def webhook():
    webhook_body = request.data
    sig_header = request.headers.get("Stripe-Signature")

    try:
        handler.handle(webhook_body, sig_header)
        return jsonify(success=True), 200
    except Exception as e:
        return jsonify(error=str(e)), 500