# Node webhook inspector

A webhook inspector accepts test events, labels familiar payloads, verifies optional signatures, and returns a compact receipt to the sender. Tokay runs it as a Function and keeps each request beside its response, duration, and logs.

Use it when you are connecting a provider and need to understand the actual bytes reaching your code before you build the full workflow. You can begin with unsigned samples, then require HMAC signatures when the sender is ready.

## Facts

- Runtime: Node.js
- Framework: Express
- Service types: Function
- Resources: None
- Required secrets: None

## What it does

Press **Send Test Event** and the request appears under **Requests** with the Function's JSON response and matching log line.

Send a payload containing an email and message and the handler labels it `form lead`. An `order.created` event receives `new order`, while anything else remains `general`.

Once `WEBHOOK_SECRET` is set, unsigned or invalid requests receive `401`. Generic SHA256 headers and Stripe style timestamped signatures are both accepted.

## Deploy it

Bring this folder to Tokay any way you like. Paste or upload it in the dashboard, push it with git, or hand it to your AI agent along with [our agent instructions](https://app.tokay.io/llms.txt). Tokay figures out the rest.

Working in Claude, ChatGPT, VS Code, or another MCP client? Connect the [Tokay MCP server](https://tokay.io/docs/platform-mcp) and ask your agent to deploy this example. It signs in through your browser, so there is no token to paste.

New to Tokay? The [getting started guide](https://tokay.io/getting-started) walks you through your first deploy.

## Try it

1. Copy the Function URL from the top of the Service page. Replace the placeholder below with that URL, then send the form event.

```bash
export FUNCTION_URL="https://your-function-url"
curl -X POST "$FUNCTION_URL/hooks/forms" \
  -H "content-type: application/json" \
  -d '{"email":"mira@example.com","message":"Could you quote the autumn workshop?"}'
```

2. Open **Requests** and confirm the response tag is `form lead`.
3. Choose **Copy as cURL** and replay the request. The new history entry gives you the same response from the same body.

## Turn on signature checks

When you are ready to reject unsigned requests, open the Function's **Environment** page and find `WEBHOOK_SECRET` under **From your code**. Choose **Set shared value**, save the secret, and deploy again.

Generic senders can put the lowercase HMAC SHA256 digest in `x-webhook-signature`, with or without the `sha256=` prefix. Stripe style signatures with `t` and `v1` fields work too.

Unsigned or invalid requests now return 401. **Send Test Event** is unsigned, so use that button before adding the secret. Afterward, replay a signed request from your provider.

## How it works

You can inspect signatures correctly because Express keeps the raw body instead of parsing and rebuilding it first. The handler checks the optional secret, applies one small tagging rule, and returns its receipt.

Tokay puts the public Function URL and request history around that code. You get a debugging surface without adding an event dashboard to the project.

## Secrets

| Name | Required | Purpose |
| --- | --- | --- |
| `WEBHOOK_SECRET` | No | Requires a valid generic or Stripe style signature. |

## Grow from here

Try [Replace a Zap](/examples/node-replace-a-zap) when each event should enter a database and feed a scheduled digest.

## Source files

- [package.json](https://tokay.io/examples/src/node-webhook-inspector/package.json)
- [src/index.ts](https://tokay.io/examples/src/node-webhook-inspector/src/index.ts)
- [tsconfig.json](https://tokay.io/examples/src/node-webhook-inspector/tsconfig.json)

## Download and source

- [Download the complete project](https://tokay.io/examples/downloads/node-webhook-inspector.zip)
- Last updated: 2026-07-31
- Example revision: `52c7b7f`
- [View this revision on GitHub](https://github.com/tokayio/tokay-examples/tree/52c7b7ffd52e157375b08f1f11ff4fbe6c498642/node-webhook-inspector)
- [Deploy a webhook](https://tokay.io/use-cases/deploy-webhook)