Como lidar com webhooks do Stripe com Functions

Aprenda como lidar com webhooks do Stripe de forma segura usando Azion Functions para processar eventos de pagamento em tempo real com performance e confiabilidade otimizadas.

Ver como Markdown

Este guia demonstra como lidar com webhooks do Stripe de forma segura usando Azion 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.

Esta demonstração mostra como aproveitar Functions para processamento seguro de webhooks mantendo conformidade PCI e performance otimizada no edge.

Requisitos

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

Código

Esse é um exemplo de código de como usar webhooks do Stripe com Azion 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

  1. Faça login na sua conta Azion via CLI:
azion login
  1. Siga os prompts de autenticação para conectar sua CLI com sua conta Azion.

Passo 2: Crie uma nova Applications a partir de um template

  1. Inicialize uma nova Applications:
azion init

  1. Selecione o template Hono Boilerplate para usar para sua aplicação browserless.

  2. Siga os prompts para configurar sua nova Applications.

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 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 Function
  • Configurar a 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

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

Passo 6: Teste entrega de webhook

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

Testando seu manipulador de webhook

Passo 1: Use Stripe CLI para teste local

  1. Instale Stripe CLI
  2. Encaminhe webhooks para seu servidor de desenvolvimento local:
stripe listen --forward-to localhost:3000/webhook
  1. Dispare eventos de teste:
stripe trigger payment_intent.succeeded
stripe trigger charge.succeeded
stripe trigger invoice.payment_succeeded

Passo 2: Teste em produção

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

Passo 3: Teste de tratamento de erros

  1. Teste com assinaturas inválidas
  2. Teste com payloads malformados
  3. Teste cenários de timeout
  4. 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

  1. Habilite registros detalhados: Registre todos os eventos de webhook e etapas de processamento
  2. Use Dashboard do Stripe: Monitore tentativas de entrega de webhook
  3. Teste localmente: Use Stripe CLI para debugging local
  4. 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
Documentação de Webhooks do Stripe Saiba mais sobre Functions