Build a Stripe webhook handler with Functions

Receive Stripe payment events on a Hono app deployed as a function, verify every signature, and handle each event type.

Last updated

View as Markdown Agent setup

In this tutorial, you will build a Stripe webhook handler that runs as a function on Azion. You will create the project, verify the signature, handle the events, store the credentials, deploy the handler, and register its URL with Stripe.

The handler is a Hono app with two routes: POST /webhook, which receives the events, and GET /, which reports the status of the service.

Prerequisites

1. Create the project

Azion CLI scaffolds the project from the Hono preset. To create it:

Authenticate the CLI

Run the login command:

azion login

The command opens a browser-based flow and stores the resulting personal token locally, so the next commands run against your account.

Initialize the project

Run the init command:

azion init
Name the project

Enter a name, or press enter to accept the suggestion the CLI prints.

Select the Hono preset
Select a template

The CLI creates the project directory with the Hono template and its configuration files.

2. Verify the webhook signature

Stripe signs every webhook request and carries the signature in the stripe-signature header. A handler that acts on an unverified request acts on any request that reaches its URL, so the signature check runs before the route.

The middleware below rejects a request with no signature, rejects a request whose signature does not match, and attaches the parsed event to the Hono context for the route handler.

The entry field of azion.config.js names the entry file of the project. Open that file and replace its contents with the Stripe client and the verification middleware:

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 // Attach the event to the context for use in the route handler
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};

A request that fails the check receives a 400 response and never reaches the route.

3. Handle the payment events

The route reads the verified event from the context and branches on its type. Every branch ends in a 200 response: Stripe retries an event that the endpoint does not acknowledge. A retry delivers an event the handler may have already acted on, so record the id of every event it processes and skip one that repeats. A retry can redeliver an event the handler already processed, so store each event.id and skip an ID already stored.

Add the webhook route, the status route, the error handler, and the export to the same file:

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 // Handle successful payment
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 // ... handle other event types
26 default:
27 console.log(`Unhandled event type ${event.type}`);
28 }
29
30 // Return a 200 response to acknowledge receipt of the event
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;

The handler answers every verified event with { "received": true }, and an event type outside the switch reaches the default branch and is logged.

export default app is the ES Modules handler pattern. For the Service Worker pattern and the steps to migrate from it, refer to Migrate handler patterns in Functions.

For the reference implementation of this handler, refer to edge-functions-examples.

4. Store the Stripe credentials

The handler reads both Stripe keys from the environment, so neither value belongs in the code. The secret key starts with sk_test_ or sk_live_, and the webhook signing secret starts with whsec_.

Store the secret key as an environment variable on your account:

azion create variables --key "STRIPE_SECRET_KEY" --value "<your-stripe-secret-key>" --secret true

Store the webhook signing secret the same way:

azion create variables --key "STRIPE_WEBHOOK_SECRET" --value "<your-stripe-webhook-secret>" --secret true

Both variables are stored on the account with the secret field set to true, which marks the value as confidential. A variable whose key contains password, pwd, secret, key, hash, encrypted, passcode, auth, or token is sent as a secret by default. A change to a variable reaches the function only after a redeploy. For the fields, the limits, and the other subcommands, refer to Environment variables.

5. Deploy the handler

Deploy the project:

azion deploy

Azion CLI builds the project, deploys it, and opens Azion Console on the page that carries the deployment logs. When the browser does not open, the terminal prints the link.

The deployment returns a domain in the format https://xxxxxxxxx.map.azionedge.net. Propagation takes a few minutes, so wait before you send the first event. The webhook route of the handler is /webhook on that domain.

6. Point Stripe at the handler

To deliver the events to the deployed handler:

Open the webhook settings

In the Stripe Dashboard, go to Developers > Webhooks.

Select your webhook endpoint
Set the endpoint URL

Enter https://<your-azion-domain>/webhook.

Save the changes

Stripe delivers to your function every event selected on that endpoint. For the event types an endpoint accepts, refer to Stripe webhooks.

7. Verify the handler

To exercise the deployed handler:

Request the status route
curl https://<your-azion-domain>/

The route returns a JSON object with three fields: status set to ok, timestamp set to the time of the request, and service set to stripe-webhooks.

Send two events the switch names
Shell
01stripe trigger payment_intent.succeeded
02stripe trigger charge.succeeded

Stripe delivers each event to the registered endpoint, and the handler answers { "received": true }. The Stripe Dashboard lists the delivery, its response code, and any retry for that endpoint.

Send an event the switch does not name
stripe trigger invoice.payment_succeeded

The handler answers { "received": true } again, and the event reaches the default branch.

Read what the handler logged
azion logs cells --tail

The terminal prints the console messages of the last 5 minutes and keeps printing new ones.

Each triggered event produces one line: PaymentIntent was successful! with the payment intent ID, Charge was successful! with the charge ID, and Unhandled event type invoice.payment_succeeded for the event the switch does not name.

To exercise the handler before a deployment, start the local development server with azion dev and forward the events to it with stripe listen --forward-to localhost:3000/webhook. Refer to Azion CLI dev.

Next steps

Environment variablesThe fields of a variable, the account and per-function limits, and every CLI subcommand that manages one.Troubleshoot function execution and logsWhat to check when a function never runs, stops before it responds, or produces no log output.Functions best practicesWhat each part of the handler does, and the design choices that keep an invocation inside its limits.Functions limitsThe CPU time, wall-clock time, sub-request, and memory ceilings a single invocation runs inside.