Construa um handler de webhooks do Stripe com Functions

Receba eventos de pagamento do Stripe em uma aplicação Hono que roda como function, verifique cada assinatura e trate cada tipo de evento.

Última atualização

Ver como Markdown Configurar agente

Neste tutorial, você vai construir um handler de webhooks do Stripe que roda como uma function na Azion. Você vai criar o projeto, verificar a assinatura, tratar os eventos, armazenar as credenciais, fazer o deploy do handler e registrar sua URL no Stripe.

O handler é uma aplicação Hono com duas rotas: POST /webhook recebe os eventos e GET / informa o status do serviço.

Pré-requisitos

1. Crie o projeto

Azion CLI monta o projeto a partir do preset Hono. Para criá-lo:

Autentique a CLI

Execute o comando de login:

azion login

O comando abre um fluxo no navegador e armazena localmente o personal token gerado, de modo que os próximos comandos rodam na sua conta.

Inicialize o projeto

Execute o comando de init:

azion init
Nomeie o projeto

Digite um nome ou pressione enter para aceitar a sugestão que a CLI exibe.

Selecione o preset Hono
Selecione um template

Azion CLI cria o diretório do projeto com o template Hono e seus arquivos de configuração.

2. Verifique a assinatura do webhook

Stripe assina cada requisição de webhook e envia a assinatura no header stripe-signature. Um handler que age sobre uma requisição não verificada age sobre qualquer requisição que chega à sua URL, por isso a verificação da assinatura roda antes da rota.

O middleware abaixo rejeita uma requisição sem assinatura, rejeita uma requisição cuja assinatura não confere e anexa o evento convertido ao contexto do Hono para o handler da rota.

O campo entry do azion.config.js indica o arquivo de entrada do projeto. Abra esse arquivo e substitua o conteúdo dele pelo cliente do Stripe e pelo middleware de verificação:

TypeScript
01import { Context, Hono } from "hono";
02import { HTTPException } from "hono/http-exception";
03import Stripe from "stripe";
04
05type Bindings = {
06 STRIPE_SECRET_KEY: string;
07};
08
09type Variables = {
10 stripeEvent: Stripe.Event;
11};
12
13export const app = new Hono<{
14 Bindings: Bindings;
15 Variables: Variables;
16}>();
17
18const stripe = new Stripe(Azion.env.get("STRIPE_SECRET_KEY") || "", {
19 apiVersion: "2025-06-30.basil",
20 typescript: true,
21});
22
23const verifyStripeWebhook = async (c: Context, next: () => Promise<void>) => {
24 try {
25 const signature = c.req.header("stripe-signature");
26 if (!signature) {
27 throw new HTTPException(400, {
28 message: "Missing stripe-signature header",
29 });
30 }
31
32 const payload = await c.req.raw.text();
33
34 const event = stripe.webhooks.constructEvent(
35 payload,
36 signature,
37 Azion.env.get("STRIPE_WEBHOOK_SECRET") || ""
38 );
39
40 // Anexa o evento ao contexto para uso no handler da rota
41 c.set("stripeEvent", event);
42 await next();
43 } catch (err) {
44 console.error("Webhook verification failed:", err);
45 return c.json({ error: "Webhook verification failed" }, 400);
46 }
47};

Uma requisição que falha na verificação recebe uma resposta 400 e nunca chega à rota.

3. Trate os eventos de pagamento

A rota lê o evento verificado no contexto e ramifica conforme o tipo dele. Toda ramificação termina em uma resposta 200: Stripe reenvia um evento que o endpoint não confirma. Um reenvio entrega um evento sobre o qual o handler já pode ter agido, então registre o id de cada evento processado e ignore um que se repita. Um reenvio pode entregar de novo um evento que o handler já processou, então armazene cada event.id e ignore um ID já armazenado.

Adicione ao mesmo arquivo a rota de webhook, a rota de status, o tratamento de erros e o export:

TypeScript
01app.post("/webhook", verifyStripeWebhook, async (c) => {
02 const event = c.get("stripeEvent");
03
04 try {
05 switch (event.type) {
06 case "payment_intent.succeeded": {
07 const paymentIntent = event.data.object as Stripe.PaymentIntent;
08 console.log("PaymentIntent was successful!", paymentIntent.id);
09 // Trate aqui o pagamento bem-sucedido
10 break;
11 }
12
13 case "payment_method.attached": {
14 const paymentMethod = event.data.object as Stripe.PaymentMethod;
15 console.log("PaymentMethod was attached!", paymentMethod.id);
16 break;
17 }
18
19 case "charge.succeeded": {
20 const charge = event.data.object as Stripe.Charge;
21 console.log("Charge was successful!", charge.id);
22 break;
23 }
24
25 // ... trate os outros tipos de evento
26 default:
27 console.log(`Unhandled event type ${event.type}`);
28 }
29
30 // Retorna uma resposta 200 para confirmar o recebimento do evento
31 return c.json({ received: true });
32 } catch (err) {
33 console.error("Error handling webhook:", err);
34 return c.json({ error: "Webhook handler failed" }, 400);
35 }
36});
37
38app.get("/", (c) => {
39 return c.json({
40 status: "ok",
41 timestamp: new Date().toISOString(),
42 service: "stripe-webhooks",
43 });
44});
45
46app.onError((err: Error, c) => {
47 console.error("Error:", err);
48 return c.json({ error: "Internal Server Error" }, 500);
49});
50
51export default app;

O handler responde a cada evento verificado com { "received": true }, e um tipo de evento fora do switch chega à ramificação default e é registrado no log.

nota — export default app é o padrão de handler ES Modules. Para o padrão Service Worker e os passos para migrar dele, consulte Migre padrões de handler em Functions.

Para a implementação de referência deste handler, consulte edge-functions-examples.

4. Armazene as credenciais do Stripe

O handler lê as duas chaves do Stripe no ambiente, então nenhum desses valores pertence ao código. A chave secreta começa com sk_test_ ou sk_live_ e a chave de assinatura do webhook começa com whsec_.

Armazene a chave secreta como variável de ambiente na sua conta:

azion create variables --key "STRIPE_SECRET_KEY" --value "<sua-chave-secreta-do-stripe>" --secret true

Armazene a chave de assinatura do webhook da mesma forma:

azion create variables --key "STRIPE_WEBHOOK_SECRET" --value "<sua-chave-de-assinatura-do-webhook>" --secret true

As duas variáveis ficam armazenadas na conta com o campo secret definido como true, o que marca o valor como confidencial. Uma variável cuja chave contém password, pwd, secret, key, hash, encrypted, passcode, auth ou token é enviada como secret por padrão. Uma alteração em uma variável só chega à function depois de um novo deploy. Para os campos, os limites e os outros subcomandos, consulte Variáveis de ambiente.

5. Faça o deploy do handler

Faça o deploy do projeto:

azion deploy

Azion CLI faz o build do projeto, faz o deploy e abre Azion Console na página que traz os logs do deployment. Quando o navegador não abre, o terminal exibe o link.

O deployment retorna um domínio no formato https://xxxxxxxxx.map.azionedge.net. A propagação leva alguns minutos, então aguarde antes de enviar o primeiro evento. A rota de webhook do handler é /webhook nesse domínio.

6. Registre a URL do handler no Stripe

Para entregar os eventos ao handler em produção:

Abra as configurações de webhook

No Stripe Dashboard, vá para Developers > Webhooks.

Selecione seu endpoint de webhook
Defina a URL do endpoint

Digite https://<seu-dominio-azion>/webhook.

Salve as alterações

Stripe entrega à sua function cada evento selecionado nesse endpoint. Para os tipos de evento que um endpoint aceita, consulte Stripe webhooks.

7. Verifique o handler

Para exercitar o handler após o deploy:

Faça uma requisição à rota de status
curl https://<seu-dominio-azion>/

A rota retorna um objeto JSON com três campos: status definido como ok, timestamp definido como o horário da requisição e service definido como stripe-webhooks.

Envie dois eventos nomeados no switch
Shell
01stripe trigger payment_intent.succeeded
02stripe trigger charge.succeeded

Stripe entrega cada evento ao endpoint registrado e o handler responde { "received": true }. O Stripe Dashboard lista a entrega, o código de resposta e qualquer reenvio desse endpoint.

Envie um evento que o switch não nomeia
stripe trigger invoice.payment_succeeded

O handler responde { "received": true } novamente e o evento chega à ramificação default.

Leia o que o handler registrou no log
azion logs cells --tail

O terminal exibe as mensagens de console dos últimos 5 minutos e continua exibindo as novas.

Cada evento disparado produz uma linha: PaymentIntent was successful! com o ID do payment intent, Charge was successful! com o ID do charge e Unhandled event type invoice.payment_succeeded para o evento que o switch não nomeia.

dica — Para exercitar o handler antes de um deploy, inicie o servidor de desenvolvimento local com azion dev e encaminhe os eventos para ele com stripe listen --forward-to localhost:3000/webhook. Consulte Azion CLI dev.

Próximos passos

Variáveis de ambienteOs campos de uma variável, os limites por conta e por function e cada subcomando da CLI que gerencia uma delas.Solução de problemas de execução e logs de funçõesO que verificar quando uma function nunca roda, é interrompida antes de responder ou não produz saída de log.Boas práticas de FunctionsO que cada parte do handler faz e as escolhas de design que mantêm uma invocação dentro dos limites.Limites de FunctionsOs tetos de tempo de CPU, tempo total, sub-requisições e memória em que uma invocação roda.