Processamento de webhooks da Stripe

Imagine you're waiting for a package. You could constantly call the delivery company (polling) to ask for updates, or they could simply call you (webhook) when the package arrives. Webhooks are automated messages sent by one system to another when a specific event occurs.

They act like a notification system, allowing applications to communicate in real-time about changes or events.

Payment processing is often asynchronous. This means an action, like a payment, might not complete instantly. It could take time, or even fail, after your user initiates it.

Stripe uses webhooks to notify your application about these crucial asynchronous events. Instead of constantly asking Stripe for updates, Stripe tells your app when a payment succeeds, a subscription renews, a refund is issued, or a failure occurs.

Stripe sends different types of webhook events depending on what happened. Each event type has a unique identifier.

• checkout.session.completed: A customer finished a Stripe Checkout session.
• invoice.payment_succeeded: A payment for an invoice (often related to subscriptions) was successful.
• customer.subscription.updated: A subscription changed status (e.g., from active to canceled).
• payment_intent.succeeded: A payment intent successfully captured funds.

These are just a few; there are many more to cover various scenarios.

To receive Stripe webhooks, your application needs a publicly accessible HTTP endpoint (a URL) that can accept POST requests. This endpoint will be the listener for all incoming Stripe events.

Here's a basic Python Flask example of what such an endpoint might look like:

Once you have your endpoint, you need to tell Stripe where to send the events. You do this in the Stripe Dashboard.

• Go to Developers > Webhooks.
• Click Add endpoint.
• Enter your public URL (e.g., https://yourdomain.com/stripe-webhook).
• Select the event types you want to receive.

For local development, you can use the Stripe CLI's stripe listen command to forward events to your local endpoint.

When an event occurs, Stripe sends a JSON payload to your endpoint. This payload contains all the details about the event, including its id, type, and the data object related to the event (e.g., a checkout.session or invoice object).

Your endpoint will read this JSON and decide what to do next based on the type of event.

This is crucial for security! Anyone could send a fake POST request to your webhook URL. To ensure an event genuinely came from Stripe and hasn't been tampered with, you must verify its signature.

Stripe includes a unique signature in the Stripe-Signature header of each webhook request. You'll use your webhook secret (from the Stripe Dashboard) to verify it.

Once an event is verified, your application can then process it based on its type. This typically involves updating your database, sending emails, or triggering other business logic.

It's common to use a switch statement or if/elif chain to handle different event types.

• Respond Quickly: Stripe expects a 200 OK response within a few seconds. If processing is heavy, do it asynchronously (e.g., send to a queue).
• Idempotency: Design your event handlers to be idempotent. Stripe might send the same event multiple times, so ensure processing an event twice doesn't cause issues.
• Error Handling: Implement robust logging and error handling. If your endpoint returns an error, Stripe will retry sending the event.
• Security: Always use HTTPS for your webhook endpoint.

In this lesson, we explored how to handle Stripe webhooks. You learned that webhooks are essential for reacting to asynchronous payment events in real-time.

• You create a dedicated endpoint in your application.
• You register this endpoint in the Stripe Dashboard.
• Crucially, you verify the webhook signature to ensure authenticity and integrity.
• Finally, you process different event types to keep your application's state synchronized with Stripe's, fulfilling orders, updating subscriptions, and more.