Process incoming webhooks with event notification handlersPublic preview

Write a function that runs whenever a dedicated callback hasn’t been registered for a specific event type. It will receive the EventNotification, plus a StripeClient and additional information about the event.

This function might log the fact that you received an unexpected event or throw an error to alert you to the unexpected state. You can also add business logic in this function if you’re handling events that your SDK doesn’t have types for.

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

As part of your migration, consider moving all of your webhook endpoint code into this function. Then, you can migrate individual event types to their own functions.

In your webhook endpoint, initialize an EventNotificationHandler, passing it your fallback callback. There’s a convenience method on StripeClient to simplify this step.

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

Next, write a function responsible for handling a specific event type. It uses the event types released with the Clover API version in September 2025.

Your callback will receive the event notification cast to the correct class. You’ll also get a StripeClient, bound to the context of the notification, which makes it easy to make additional API calls without juggling account ids.

# 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}")

You can register zero or more callbacks. If you don’t register any, all events will be routed to your fallback callback.

Send incoming POST bodies into the handler. This replaces most of the original code in your webhook endpoint.

@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