Como lidar com webhooks do Stripe com Edge Functions

Este guia demonstra como lidar com webhooks do Stripe de forma segura usando Azion Edge Functions. Você aprenderá a processar eventos de pagamento em tempo real, verificar assinaturas de webhook e construir um sistema robusto de processamento de pagamentos no edge.

Requisitos

Antes de começar, certifique-se de ter:

Uma conta na Azion
Uma conta no Stripe com acesso à API
Azion CLI instalada e configurada
Node.js versão 18 ou superior

Código

Esse é um exemplo de código de como usar webhooks do Stripe com Azion Edge Functions. O exemplo completo do código você pode encontrar nesse repositório do GitHub.

import { Context, Hono } from "hono";
import { fire } from "hono/service-worker";
import { HTTPException } from "hono/http-exception";
import Stripe from "stripe";

type Bindings = {
  STRIPE_SECRET_KEY: string;
};

type Variables = {
  stripeEvent: Stripe.Event;
};

// Initialize Hono app with proper types
export const app = new Hono<{
  Bindings: Bindings;
  Variables: Variables;
}>();

// Initialize Stripe with your secret key
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY || "", {
  apiVersion: "2025-06-30.basil",
  typescript: true,
});

// Middleware to verify the webhook signature
const verifyStripeWebhook = async (c: Context, next: () => Promise<void>) => {
  try {
    const signature = c.req.header("stripe-signature");
    if (!signature) {
      throw new HTTPException(400, {
        message: "Missing stripe-signature header",
      });
    }

    const payload = await c.req.raw.text();

    // Verify the webhook signature
    const event = stripe.webhooks.constructEvent(
      payload,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET || ""
    );

    // Attach the event to the context for use in the route handler
    c.set("stripeEvent", event);
    await next();
  } catch (err) {
    console.error("Webhook verification failed:", err);
    return c.json({ error: "Webhook verification failed" }, 400);
  }
};

// Webhook endpoint
app.post("/webhook", verifyStripeWebhook, async (c) => {
  const event = c.get("stripeEvent");

  try {
    // Handle the event
    switch (event.type) {
      case "payment_intent.succeeded": {
        const paymentIntent = event.data.object as Stripe.PaymentIntent;
        console.log("PaymentIntent was successful!", paymentIntent.id);
        // Handle successful payment
        break;
      }

      case "payment_method.attached": {
        const paymentMethod = event.data.object as Stripe.PaymentMethod;
        console.log("PaymentMethod was attached!", paymentMethod.id);
        break;
      }

      case "charge.succeeded": {
        const charge = event.data.object as Stripe.Charge;
        console.log("Charge was successful!", charge.id);
        break;
      }

      // ... handle other event types
      default:
        console.log(`Unhandled event type ${event.type}`);
    }

    // Return a 200 response to acknowledge receipt of the event
    return c.json({ received: true });
  } catch (err) {
    console.error("Error handling webhook:", err);
    return c.json({ error: "Webhook handler failed" }, 400);
  }
});

// Health check endpoint
app.get("/", (c) => {
  return c.json({
    status: "ok",
    timestamp: new Date().toISOString(),
    service: "stripe-webhooks",
  });
});

// Error handling
app.onError((err: Error, c) => {
  console.error("Error:", err);
  return c.json({ error: "Internal Server Error" }, 500);
});

fire(app, { env: { STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY! } });

Deploy na Azion

Passo 1: Autentique-se na Azion

Faça login na sua conta Azion via CLI:

azion login

Siga os prompts de autenticação para conectar sua CLI com sua conta Azion.

Passo 2: Crie uma nova Edge Application a partir de um template

Inicialize uma nova Edge Application:

azion init

Selecione o template Hono Boilerplate para usar para sua aplicação browserless.
Siga os prompts para configurar sua nova Edge Application.

Passo 3: Crie secrets para credenciais do Stripe

Para segurança, armazene suas credenciais do Stripe como secrets:

azion create secret STRIPE_SECRET_KEY
azion create secret STRIPE_WEBHOOK_SECRET

Quando solicitado, digite suas respectivas credenciais do Stripe. Isso garante que seus dados sensíveis sejam criptografados e seguros.

Passo 4: Faça o deploy da Edge Function

Faça o deploy de seu manipulador de webhook na edge network da Azion:

azion deploy

O processo de deploy irá:

Fazer upload do código da sua Edge Function
Configurar a edge application
Configurar as regras de roteamento necessárias
Configurar variáveis de ambiente e secrets
Fornecer um domínio único

Passo 5: Atualize a configuração de webhook do Stripe

Após o deploy, você receberá um domínio como https://xxxxxxx.map.azionedge.net
Vá para seu Dashboard do Stripe > Developers > Webhooks
Edite seu endpoint de webhook
Atualize a URL para https://xxxxxxx.map.azionedge.net/webhook
Salve as alterações

Passo 6: Teste entrega de webhook

Dispare eventos de teste no Dashboard do Stripe
Monitore entrega e respostas de webhook
Verifique logs da Edge Function para confirmação de processamento

Testando seu manipulador de webhook

Passo 1: Use Stripe CLI para teste local

Instale Stripe CLI
Encaminhe webhooks para seu servidor de desenvolvimento local:

stripe listen --forward-to localhost:3000/webhook

Dispare eventos de teste:

stripe trigger payment_intent.succeeded
stripe trigger charge.succeeded
stripe trigger invoice.payment_succeeded

Passo 2: Teste em produção

Use Dashboard do Stripe para enviar webhooks de teste
Monitore entrega de webhook e tentativas de retry
Verifique códigos de resposta e tempos de processamento
Verifique precisão de manipulação de eventos

Passo 3: Teste de tratamento de erros

Teste com assinaturas inválidas
Teste com payloads malformados
Teste cenários de timeout
Verifique mecanismos de retry

Melhores práticas de segurança

Verificação de webhook

Sempre verifique assinaturas: Nunca processe webhooks não verificados
Use HTTPS: Certifique-se de que todos os endpoints de webhook usem HTTPS
Valide payload: Verifique estrutura do evento e campos obrigatórios
Implemente proteção contra replay: Rastreie IDs de eventos processados

Gerenciamento de secrets

Use secrets da Azion: Armazene credenciais de forma segura
Rotacione secrets regularmente: Atualize secrets de webhook periodicamente
Limite acesso: Restrinja acesso a secrets às funções necessárias
Monitore uso: Rastreie acesso e uso de secrets

Monitoramento e registro

Registro de eventos

function logWebhookEvent(event, status, processingTime) {
    console.log({
        event_id: event.id,
        event_type: event.type,
        status,
        processing_time: processingTime,
        timestamp: new Date().toISOString()
    });
}

Monitoramento de performance

Tempos de resposta: Monitore velocidade de processamento de webhook
Taxas de sucesso: Rastreie processamentos bem-sucedidos versus falhos
Padrões de erro: Identifique cenários comuns de falha
Frequência de retry: Monitore tentativas de retry de webhook

Solução de problemas

Problemas comuns e soluções

Falhas de verificação de assinatura: Verifique configuração de secret do webhook
Erros de timeout: Otimize lógica de processamento para velocidade
Processamento duplicado: Implemente verificações de idempotência
Eventos perdidos: Verifique configuração do endpoint de webhook

Dicas de debugging

Habilite registros detalhados: Registre todos os eventos de webhook e etapas de processamento
Use Dashboard do Stripe: Monitore tentativas de entrega de webhook
Teste localmente: Use Stripe CLI para debugging local
Verifique assinaturas: Verifique cálculo de assinatura de webhook

Próximos passos

Implemente registro e monitoramento abrangente de eventos
Adicione funcionalidade de replay de webhook para eventos falhados
Integre com seu sistema de processamento de pagamentos existente
Implemente mecanismos avançados de detecção de fraude
Dimensione processamento de webhook para cenários de alto volume