Forem: Phil Leggetter

How to Make Your AI Agent Get Webhooks Right (A Guide to Webhook Skills)

Phil Leggetter — Wed, 18 Feb 2026 15:27:46 +0000

When I ask my AI coding agent to set up webhooks from a new API (Stripe, Shopify, GitHub, whatever), the code it generates often looks fine until I run it. Then I hit signature verification failures, wrong raw body handling, or idempotency bugs that process the same event twice. Sound familiar?

I created webhook-skills to fix that. They're agent skills for webhooks: an open-source collection of provider- and framework-specific instructions and runnable examples that AI coding agents can load so they implement webhooks correctly the first time. In this guide I'll walk through how to use them, what's in them, and how you can contribute or request skills that are missing.

Why Agents Get Webhooks Wrong

At Hookdeck we process billions of webhooks a week, and we've seen every failure mode: signature mismatches from body parsing middleware, framework-specific gotchas that only show up in production, and so on. AI agents struggle with the same things. Their training data goes stale quickly. API versions change, security practices evolve, and the details that matter (raw body handling, middleware order, encoding) aren't in the model.

Research from PostHog on LLM code generation backs this up: the most reliable way to get correct code isn't the model's general knowledge; it's giving it specific, known-working examples to reference. Webhook skills are built to fill that gap.

How Webhook Skills Fix It

Webhook-skills is built on the Agent Skills specification, an open standard for packaging knowledge that agents can consume. In practice that means:

Runnable examples: complete, minimal apps the agent can reference and adapt, not just snippets.
Provider-specific guidance: Stripe's raw body requirement, Shopify's HMAC encoding, and other gotchas we see trip up developers.
Framework-aware implementations: how Next.js, Express, and FastAPI handle request bodies, middleware order, and async patterns.
Staged workflows: verify signature first, parse payload second, handle idempotently third.

When I ask my agent to "add Stripe webhooks to my Next.js app," it doesn't hallucinate a generic handler. It has the exact patterns for App Router body handling, preserving the raw body before verification, and pulling the webhook secret from env with the right naming. That's the difference.

How to Use Them

Install the skills

I use npx skills to add webhook-skills to my project. First I list what's available, then I install the skills I need:

# List available skills
npx skills add hookdeck/webhook-skills --list

# Install best-practice patterns (verify → parse → handle idempotently)
npx skills add hookdeck/webhook-skills --skill webhook-handler-patterns

# Install specific provider skills
npx skills add hookdeck/webhook-skills --skill stripe-webhooks
npx skills add hookdeck/webhook-skills --skill shopify-webhooks

I usually install webhook-handler-patterns plus the provider skill for whichever API I'm integrating. That gives my agent both the general flow and the provider-specific details.

How to prompt

Once the skills are installed, I prompt naturally. For example:

"Add Shopify webhook handling to my Express app."
"Set up Stripe webhooks in my Next.js app."
"Implement GitHub webhook verification in my FastAPI service."

The agent has the patterns; I don't need to spell out raw body or signature verification. It already knows.

Local testing (optional)

When I'm testing webhooks locally, I use the Hookdeck CLI. It gives me a public URL that tunnels to my local server and a UI to inspect and replay requests:

npm i -g hookdeck-cli
# or: brew install hookdeck/hookdeck/hookdeck

hookdeck listen 3000 --path /webhooks/stripe

No account required to get started. The skills work with or without Hookdeck; they're just complementary when you want to receive real webhooks on localhost.

What's Available (and What's Missing)

Right now webhook-skills covers the providers and frameworks we see most often:

Providers: Stripe, Shopify, GitHub, OpenAI, Resend, Paddle, ElevenLabs, Chargebee, and more.

Frameworks: Next.js, Express, and FastAPI.

Each provider skill includes signature verification, event handling guidance, common failure modes, and testing tips for local dev. Coverage isn't complete yet. If you need a provider we don't have or you want to contribute, see the next section.

How to Contribute and Ask for Skills

Request a skill: If you're integrating a provider we don't support yet, open an issue on GitHub with a title like "Skill request: [Provider] webhooks". Describe the provider and your framework if relevant. I use these to prioritize what to add next.

Contribute a skill: If you've built a webhook integration you're proud of, PRs for new providers or frameworks are welcome. The repo is hookdeck/webhook-skills. Check the existing skills for structure and open a PR.

API and platform maintainers: If you maintain a webhook-producing API and want AI coding agents to implement your webhooks correctly out of the box, I'd love a skill from you. Open an issue or PR and we can align on format and content.

Give It a Shot

If you've ever lost an afternoon to webhook signature verification or body parsing, try webhook-skills the next time you're wiring up an integration. Install the skills, prompt your agent, and you might find it finally does what you meant.

Links:

webhook-skills on GitHub
Hookdeck CLI (optional, for local webhook testing)

Have feedback or want to request or contribute a skill? Open an issue.

Introducing The Event Destinations Initiative

Phil Leggetter — Thu, 27 Feb 2025 13:57:21 +0000

The Event Destinations Initiative is a community effort aimed at creating a model for event interoperability between event producers and their consumers. This initiative focuses on providing a set of guidelines for managing event destinations, ensuring seamless integration, improved reliability, greater event delivery choice, and a much-improved developer experience.

What are Event Destinations?

Event Destinations are the endpoints where API platform events are delivered and consumed. Event destinations can include webhook endpoints, message queues, APIs, event gateways, and other services that handle event data. Webhooks are the most ubiquitous form of event destination, but the Event Destinations Initiative aims to establish a set of guidelines for API platforms to provide additional event delivery options offering more choice, improved reliability at scale, and an overall better developer experience.

What is the Event Destinations Initiative?

The Event Destinations Initiative is a collaborative project that aims to create a set of guidelines for defining, managing, and utilizing event destinations across platforms and services.

Key Features

Standardization: Establishing a common set of guidelines and best practices for event destinations.
Interoperability: Ensuring compatibility across different platforms and services.
Scalability: Providing solutions that can scale with the growing demands of modern applications.
Reliability: Enhancing the reliability and fault tolerance of event-driven architectures.

Benefits

Simplified Integration: Easier integration with commonly used services and platforms.
Improved Efficiency: Streamlined event publishing, routing, and ingestion.
Enhanced Reliability: More robust and fault-tolerant event handling for both the publisher and consumer.
Future-Proofing: A forward-looking approach that anticipates future needs and challenges.

What Supporters are Saying

In his book Flow Architectures, James Urquhart envisions a future where APIs are inherently asynchronous, with synchronous APIs being reserved only for scenarios where they are truly necessary.

The Event Destinations Initiative represents a significant step toward realizing that vision. Enabling API producers to adopt the most efficient and performant methods for sending and receiving asynchronous, non-blocking data is a development I wholeheartedly support—particularly when it is driven by a collaborative and open effort.

This direction strongly aligns with the vision we champion at AsyncAPI, and the synergy between these efforts is both promising and exciting. I am eager to see the Event Destinations Initiative succeed and contribute to the evolution and blending of API and EDA ecosystems.

-- Fran Méndez, Founder @ AsyncAPI Initiative

I've been working with (and often against) webhooks for years, both as a consumer and an implementer, always wishing that we as an industry could come up with something better. In my opinion, Event Destinations are exactly that.

-- Paul Asjes, Developer Experience Engineer @ ElevenLabs

Get Involved

We invite developers, architects, and organizations to join us in this initiative. By collaborating, we can build a more efficient and reliable event-driven ecosystem.

Visit eventdestinations.org to learn more and get involved.

Free ngrok alternative for async web dev - the Hookdeck CLI

Phil Leggetter — Mon, 29 Jul 2024 18:31:55 +0000

ngrok is great. It's been the go-to for many a web developer who wants to be able to expose a locally running web application to the public Internet for many years. And it's still a great solution. However, ngrok has changed in ways that have resulted in a much poorer developer experience and there are now better tools for some of the jobs that ngrok was originally the go-to for.

What's changed with ngrok?

ngrok used to be free and only required an account for "premium features". Now, you need an ngrok account no matter your use case.
There's a 1GB limit a month on data transfer (in all fairness, this should be more than enough for development)
The free ephemeral/random domains (the domain name changes every time you restart ngrok) have always been a bit of a pain. The first paid plan used to come with 3 subdomains but now only comes with one, making exposing multiple services at the same time more costly.

More broadly, Their product focus has shifted reasonably dramatically from supporting use cases such as:

Temporarily sharing a website that is only running on your development machine

Demoing an app at a hackathon without deploying

Developing any services that consume webhooks (HTTP callbacks) by allowing you to replay those requests

Debugging and understanding any web service by inspecting the HTTP traffic

Running networked services on machines that are firewalled off from the internet

To:

All-in-one API gateway, Kubernetes Ingress, DDoS protection, firewall, and global load balancing as a service.

So, ngrok has shifted focus away from supporting development use cases. Therefore, it's likely time to try an alternative tool that has been built to specifically support your use case.

The rest of this post will show how the Hookdeck CLI can be used to receive asynchronous events (a.k.a. webhooks) from third-party services such as Stripe, Shopify, or Twilio. If you're looking for a tool that solves the other use cases, take a look at the awesome tunneling repo.

What is synchronous web development?

As per the title of this post, the Hookdeck CLI is built to support asynchronous web development. By this, I mean requests, such as webhooks from an API service, are received and proxied onto the application running locally. However, the response from the local service is not passed back to the API service that made the request.

The Hookdeck CLI and the Hookdeck Event Gateway are built to support asynchronous messaging with event-driven applications and not the request/response paradigm. Therefore, you can't use the Hookdeck CLI to expose and serve a locally running website or request/response API. If you want to send the result of some work to another service, you should make a separate request to that service.

Using the Hookdeck CLI as a free alternative to ngrok for webhooks

The next section walks through installing the Hookdeck CLI, creating and running a local web server (which you can skip if you already have this running), creating a localtunnel using the CLI, sending test webhook events, and replaying webhooks using the Hookdeck Console.

This guide will use the Node.js runtime. If you prefer to use Python, you can run through a using the Hookdeck CLI with a Python server to receive webhooks guide.

Install the Hookdeck CLI

Via NPM:

npm i hookdeck-cli -g

On Mac:

brew install hookdeck/hookdeck/hookdeck

On Windows:

scoop bucket add hookdeck https://github.com/hookdeck/scoop-hookdeck-cli.git
scoop install hookdeck

There are also instructions for installing on Linux.

Create and run a localhost Node.js web server

Open your terminal and navigate to a directory for your project.

Install Express to use as the web server:

npm i --save express

Create a server.js file in the project root:

const express = require('express')
const app = express()

app.use(express.json());

const port = 3030;

app.post("/", (req, res) => {
    console.log({ webhook_received: new Date().toISOString(), body: req.body });
    res.json({ status: "ACCEPTED" });
});

app.listen(port, () => {
    console.log(`🪝 Server running at http://localhost:${port}`);
});

Run the server:

node server.js

Use the Hookdeck CLI to create a localtunnel

Run the following command in a new terminal window to create a localtunnel:

hookdeck listen 3030 my-webhook

The output will be similar to the following:

Dashboard
👤 Console URL: https://api.hookdeck.com/signin/guest?token={token}
Sign up in the Console to make your webhook URL permanent.

Sources
🔌 my-webhook URL: https://hkdk.events/wggd60fl5cxw20

Connections
my-webhook -> my-webhook-to-cli forwarding to /

> Ready! (^C to quit)

Test receiving a webhook with a cURL command

Run the following cURL command to act as an inbound webhook, replacing the URL with the Event URL from the Hookdeck CLI output:

curl -X POST https://hkdk.events/cnzpo680rdhejk \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, World!"}'

The cURL command output will be similar to the following:

{"status":"SUCCESS","message":"Request handled by Hookdeck. Check your dashboard to inspect the request: https://dashboard.hookdeck.com/requests/req_[id]","request_id":"req_[id]"}%

You will see the terminal running the Hookdeck CLI log the inbound webhook:

2024-07-09 19:06:46 [200] POST http://localhost:3030/ | https://console.hookdeck.com/?event_id={id}

You will also see the Python server log the inbound webhook:

{
  webhook_received: '2024-07-25T10:08:22.945Z',
  body: { message: 'Hello, World!' }
}

Trigger a test webhook using the Hookdeck Console

Open the Console URL from your terminal in your browser.

Choose a Sample Webhook Provider from the list of Example Webhooks. For example, Stripe.

Select a Sample Webhook Type from the list on the right. For example, invoice.created.

Click Send.

The Hookdeck Console will show the test webhook has been triggered. You can also inspect the webhook payload and the localhost web server response.

You will see the terminal running the Hookdeck CLI log the inbound webhook:

2024-07-09 19:06:46 [200] POST http://localhost:3030/webhook | https://console.hookdeck.com/?event_id={id}

You will also see the Python server log the inbound webhook:

{
  "id": "evt_1MhUT7E0b6fckueStwy86nfu",
  "object": "event",
  "api_version": "2022-11-15",
  "created": 1677833999,
  "data": {
    ...
  },
  "type": "invoice.created"
}

Replay a webhook

To replay the webhook, go to the Hookdeck Console and click on the Resend to destination button.

Receive a webhook from an API platform

Copy the Event URL from the Hookdeck CLI output. You can also find the same URL in the Hookdeck Console.

Go to the API provider platform, such as Resend, Twilio, Shopify, or Stripe, and register the Hookdeck URL as the webhook URL with the provider.

Trigger a webhook from your selected API provider to see a log entry in the Hookdeck Console.

You will also see the webhook logged in the Hookdeck CLI:

2024-07-09 19:45:57 [200] POST http://localhost:3030/webhook | https://console.hookdeck.com/?event_id={id}

And by the Node.js server running in your local development environment:

{
  "to": "{to_number}",
  "from": "{from_number}",
  "channel": "sms",
  "message_uuid": "461c9502-3c2f-4af9-8862-c5a8eccf6cfe",
  "timestamp": "2024-07-09T18:45:56Z",
  "usage": {
    "price": "0.0057",
    "currency": "EUR"
  },
  "message_type": "text",
  "text": "Inbound SMS from the Vonage API",
  "context_status": "none",
  "origin": {
    "network_code": "23415"
  },
  "sms": {
    "num_messages": "1",
    "count_total": "1"
  }
}

And that's it!

You have successfully received a webhook on your local development environment using the Hookdeck CLI. You also inspected the webhook payload and server response, and replayed a webhook using the Hookdeck Console.

Learn more about Hookdeck

This guide demonstrated how to use the Hookdeck CLI as a replacement for ngrok for local asynchronous web development. The Hookdeck CLI is free to use, and you don't need a Hookdeck account.

If you're interested in finding out more about Hookdeck including features such as transformations, and filtering, benefitting from functionality like configurable retries, and generally using Hookdeck as your reliable inbound webhook infrastructure, head to hookdeck.com

Add Webhook Verification, Queueing, Filtering, and Retry Logic to Any Vercel Deployed Endpoint

Phil Leggetter — Mon, 06 May 2024 18:38:18 +0000

Today we're excited to announce the Hookdeck Vercel Middleware. Vercel middleware that convert any Vercel application endpoint into an asynchronous endpoint with authentication, filters, queueing, throttling, and retry logic.

Every month, we deliver hundreds of thousands of asynchronous events to Vercel application endpoints, so we want to make debugging and building with webhooks and other asynchronous messaging use cases on Vercel even easier.

The Hookdeck Vercel Middleware requires minimal effort (install + simple configuration) and a DX that fits into a code-first workflow. So, within a few minutes, you've converted a Next.js route, for example, into a reliable and feature-rich asynchronous endpoint.

Along with the simple setup, I believe this solves a real problem with numerous use cases. The main one is handling webhooks (Stripe, Shopify, Twilio, etc.) at a scale where you really don't want to miss a webhook.

Here's a 5-minute video of our CEO and co-founder, Alex, installing, configuring, and deploying a Next.js app:

You can see the quickstart instructions (along with the middleware source) in the Hookdeck Vercel Middleware GitHub repo

There's also example Next.js app with a deployed demo.

Let us know what you think.

Building and measuring a sign up funnel with Supabase, Next.js, and PostHog

Phil Leggetter — Thu, 21 Oct 2021 17:08:15 +0000

With the number of software frameworks and services available to help with developer productivity and feature building, it's never been a better time to be a software developer. One of most important things you'll have to build, whether building a SaaS, developer tool, or consumer app, is a sign up flow that begins on a landing page and ideally results in a successful sign up. The purpose of this sign up flow is to get as many real users through to being successfully signed up on your app or platform. So, it's important that you can measure whether your sign up flow is converting and where any potential sign ups are dropping out of that funnel.

In this tutorial, we'll create a simple sign up flow in a Next.js app, starting with a Supabase example for authentication. We'll then look at how you can instrument that sign up flow using the PostHog JavaScript SDK and create a sign up funnel visualization within PostHog to analyze the success - or failure - of the sign up flow.

Before you begin

The application in this tutorial is built entirely upon open-source technologies:

Next.js is feature rich, Node.js open-source React framework for building modern web apps.
Supabase is an open-source alternative to Firebase offering functionality such as a Postgres database, authentication, realtime subscriptions and storage.
PostHog is an open-source product analytics platform with features including feature flags, session recording, analysis of trends, funnels, user paths, and more.

To follow this tutorial along, you need to have:

A self-hosted instance of PostHog or sign up for PostHog Cloud
A self-hosted instance of Supabase or sign up for a hosted Supabase account
Node.js installed

It's easier to get up an running with the cloud hosted options. If you want to go with self-hosted then the DigitalOcean PostHog 1-click deployment makes getting started with PostHog much easier. For Supabase, the Docker setup appears to be the best option.

Bootstrap sign up with Supabase Auth

Rather than building sign up from scratch, let's instead start with an existing Supabase-powered example.

Run the following in your terminal to bootstrap a Next.js application with pre-built sign up and login functionality:

npx create-next-app --example https://github.com/PostHog/posthog-js-examples/tree/bootstrap/supabase-signup-funnel

The output will look similar to the following:

$ npx create-next-app --example https://github.com/PostHog/posthog-js-examples/tree/bootstrap/supabase-signup-funnel
✔ What is your project named? … nextjs-supabase-signup-funnel
Creating a new Next.js app in /Users/leggetter/posthog/git/nextjs-supabase-signup-funnel.

Downloading files from repo https://github.com/PostHog/posthog-js-examples/tree/bootstrap/supabase-signup-funnel. This might take a moment.

Installing packages. This might take a couple of minutes.

Initialized a git repository.

Success! Created nextjs-supabase-signup-funnel at /Users/leggetter/posthog/git/nextjs-supabase-signup-funnel

You'll be prompted for a name for your app and the files will be downloaded into a directory with that name. The directory structure of your app will look as follows:

.
├── README.md
├── components
│   └── Auth.js
├── lib
│   └── UserContext.js
├── package.json
├── pages
│   ├── _app.js
│   ├── api
│   │   ├── auth.js
│   │   └── getUser.js
│   ├── auth.js
│   └── profile.js
├── .env.local.example
├── style.css
└── utils
    └── initSupabase.js

components/Auth.js is the sign up, login, magic link, and forgot password component that makes use of Supabase Auth.
lib/UserContext.js provides functionality to get the current user from within a component wrapped in a <UserContext />, if a user is logged in.
pages/_app.js a Next.js custom app component used to initialize all pages.
pages/api/* serverless API endpoints used within the Supabase authentication.
pages/auth.js is the authentication page that uses the Auth component.
pages/profile.js is a page used to demonstrate server-side rendering.
.env.local.example environment variables/configuration.
styles.css basic styling.
utils/initSupabase.js initializes a Supabase client used to interact with Supabase.

Now we understand the basic structure of the bootstrapped application, let's get it up and running.

The one last piece of setup that's required before running the app is to create a Supabase project, set some auth config, and add the credentials from that to a .env.local. To create the .env.local run:

cp .env.local.example .env.local

Now, head to the Supabase dashboard to create a project. Click the New project button and you'll be presented with a "Create new project" dialog.

You may need to select an Organization. You will need to enter details for a project name, database password, and choose a deployment region. Once done, click the Create new project button.

You'll then be presented with a page showing Project API keys and Project Configuration.

Update the contents of .env.local as follows:

Update the NEXT_PUBLIC_SUPABASE_URL value to be the URL from Project Configuration
Update the NEXT_PUBLIC_SUPABASE_ANON_KEY value to be the API key tagged with anon and public from Project API keys

Next, within the Supabase dashboard project settings select Auth settings and add http://localhost:3000/auth to the Additional Redirect URLs field.

With the Supabase configuration in place, we can run the app with:

npm run dev

You can then navigate to http://localhost:3000/auth to try out the Supabase authentication functionality including sign up, login, login/sign up with magic link (email), and forgot password.

When you're signed up and logged in the UI will look like this:

We'll focus on sign up for our application, so try out the sign up with email and password functionality as well as the magic link sign up (note magic link emails for a single email address can be sent once per 60 seconds).

Once you're familiar with Supabase Auth functionality, we're ready to start to build a simple traditional sign up funnel.

Build a sign up funnel

The goal of this tutorial is to demonstrate how to instrument and measure a sign up flow. So, let's create a very simple sign up flow as follows:

User lands on the main website landing page which has two CTAs (call-to-actions) of SignUp. One in the header and one in the landing page hero.
User clicks on one of the sign up buttons and is taken to the sign up page.
User enters their details to sign up and submits the form.
User receives registration verification email.
User clicks the link in the email and successfully signs up.

Signup flow landing page

We'll keep the landing page really simple. Create a new file, pages/index.js, with the following content:

import Link from 'next/link'

const curlPostCmd = `
curl -d '{"key1":"value1", "key2":"value2"\}' \\
     -H "Content-Type: application/json" \\
     -X POST https://api.awesomeapi.dev/data
`

const curlGetCmd = `
curl -d https://api.awesomeapi.dev/data/{id}
`

const Index = () => {
  return (
    <div style={{ maxWidth: '520px', margin: '96px auto', fontSize: "14px" }}>

        <nav>
            <ul>
                <li className="logo">
                    <Link href="/">
                        <a>Awesome API</a>
                    </Link>
                </li>
                <li>
                    <Link href="/auth">
                        <a>
                            <button>
                                SignUp
                            </button>
                        </a>
                    </Link>
                </li>
            </ul>
        </nav>

        <header>
            <h1 className="logo">Awesome API</h1>
            <h2>Instantly build awesome functionality</h2>
            <Link href="/auth">
                <a>
                    <button>
                        SignUp
                    </button>
                </a>
            </Link>
        </header>

        <main>
            <h2><code>POST</code> something Awesome</h2>
            <pre>
                <code>
                    {curlPostCmd.trim()}
                </code>
            </pre>

            <h2><code>GET</code> something Awesome</h2>
            <pre>
                <code>
                    {curlGetCmd.trim()}
                </code>
            </pre>
        </main>

        <footer>©️Awesome API 2021</footer>

    </div>  
  )
}

export default Index

As planned, the page has two CTA <button> elements that send the user to the /auth page for sign up. One button is in the header and one is in what you could class as a "hero" location.

This will result in an "Awesome API" landing page that looks as follows:

Feel free to rebrand!

Now that a landing page is in place we have all the assets required for a basic sign up flow that we want the user to successfully navigate through.

Integrate with PostHog

A user can now sign up with our app but there are a number of potential drop-off points within the funnel. So, let's integrate the PostHog JavaScript SDK to instrument the user sign up journey.

Add two new environment variables to .env.local that will be used with the PostHog JavaScript SDK:

NEXT_PUBLIC_POSTHOG_API_KEY=your_posthog_api_key
NEXT_PUBLIC_POSTHOG_HOST=your_posthog_host

The value for NEXT_PUBLIC_POSTHOG_API_KEY can be found via Project in the left-hand menu of your PostHog app, underneath the Project API Key heading.

The value for NEXT_PUBLIC_POSTHOG_HOST is the public URL for your running PostHog instance. If you're using cloud, this is https://app.posthog.com.

With the required config in place we can install the PostHog JavaScript SDK:

npm i -S posthog-js

Create a new file, utils/initPostHog.js, and within it add code to initialize the PostHog JavaScript client:

import posthog from 'posthog-js'

export const initPostHog = () => {
    if(typeof window !== 'undefined') {
        posthog.init(process.env.NEXT_PUBLIC_POSTHOG_API_KEY, {
            api_host: process.env.NEXT_PUBLIC_POSTHOG_HOST,
        })
    }

    return posthog
}

The file exports a single function, initPostHog, that checks to ensure that the current runtime is the browser and, if so, initializes the PostHog JavaScript client with the config we've just stored. It also returns the posthog client instance so we can use within our app.

PostHog JS has an autocapture feature that automatically captures browser events (this can be disabled). However, it won't capture navigation events in Next.js where the window doesn't reload, so we need to add some custom code to capture navigations.

Open up pages/_app.js and add this code within the MyApp function:

import { useEffect } from 'react'
import { useRouter } from 'next/router'
import { initPostHog } from '../utils/initPostHog'

export default function MyApp({ Component, pageProps }) {

  const router = useRouter()

  useEffect(() => {
    // Init for auto capturing
    const posthog = initPostHog()

    const handleRouteChange = () => {
      if(typeof window !== 'undefined') {
        posthog.capture('$pageview')
      }
    }

    router.events.on("routeChangeComplete", handleRouteChange)

    return () => {
      router.events.off("routeChangeComplete", handleRouteChange)
    };
  }, [router.events])

Here, we import the React useEffect and Next.js Router hooks. Within the useEffect hook we initialize the PostHog JS client using the function we've just created and bind to a routeChangeComplete on the Next.js router, handling the event within the handleRouteChange function. When this function is called, we manually trigger a $pageview event using PostHog JS with posthog.capture('$pageview').

Now, restart your application so it picks up the new config in .env.local and head over to the Events section within your PostHog instance and you'll see new events appear as you test out the sign up flow.

Here's how some of the events can tie in to the flow we're trying to build:

Step	Event	Url / Screen
1. User lands on the main website landing page	Pageview	locahost:3000/
2. User clicks on one of the sign up buttons	clicked button with text "SignUp"	locahost:3000/
3. User enters their details to sign up and submits the form	submitted form	localhost:3000/auth
4. User receives registration verification email	no event	outside of app
5. User clicks the link in the email and successfully signs up	no event	localhost:3000/auth

From the above table, you can see that we can track everything up until the sign up form submission.

It is theoretically possible to track the step 4, email verification, if the email provider exposes an email sent notification mechanism via something like as a webhook. So, if Supabase offered a webhook when auth emails were sent we could track this from the server.

However, we need and should be able to track step 5, when the user has successfully signed up. We know that the user lands on /auth when they are logged in. If we look at the code for that page there is a user variable that is set if the user is logged in. So, let's update /pages/auth.js so we can track a logged in user. First, include the initPostHog utility:

import { initPostHog } from '../utils/initPostHog'

Next, update the Index definition:

const Index = () => {
  const { user, session } = useUser()
  const { data, error } = useSWR(session ? ['/api/getUser', session.access_token] : null, fetcher)
  const [authView, setAuthView] = useState('sign_up')

  const posthog = initPostHog()

  if(user) {
    posthog.identify(user.email, user)
    posthog.capture('loggedIn')
  }

In the above code we utilize the initPostHog function again to reference an initialized PostHog JS instance. We then make two function calls:

posthog.identify(user.email, user) - since the user is logged in we can identify them. We pass in user.email, their email address, as a distinct identifier. We also pass in the Supabase user variable so PostHog has access to additional user data.
posthog.capture('loggedIn') - this triggers a simple loggedIn event that we can use to identify the user as successfully having logged in.

If you now go through the login flow, you can map all the required events in PostHog to the sign up funnel that we're building.

You'll also see the point at which posthog.identify is called since the Person associated with the event is now listed with each event entry.

Note: posthog.identify is being called twice as the Index function is likely being called twice during the React component life cycle as the values of state variables change.

Create a sign up funnel in PostHog

Now that we have all the events for our sign up flow we can define a funnel to analyze the user journey and identify drop-off points.

First, let's recap the events in the funnel and include the new loggedIn event:

Step	Event	Url / Screen
1. User lands on the main website landing page	Pageview	locahost:3000/
2. User clicks on one of the sign up buttons	clicked button with text "SignUp"	locahost:3000/
3. User enters their details to sign up and submits the form	submitted form	localhost:3000/auth
4. User receives registration verification email	no event	outside of app
5. User clicks the link in the email and successfully signs up	loggedIn	localhost:3000/auth

To begin defining a funnel click on the New Insight left-hand menu item within PostHog and select the Funnels tab.

On the left-hand side of the view there is a panel with Graph Type and Steps headings. The Graph Type value is set to Conversion steps, which is what we want. The first of the Steps is set to Pageview. As we flesh out the steps, the funnel visualization will appear on the right.

Step 1 - User lands on landing page

The first step within the funnel is the user landing on the main website landing page with a path of /. So, the event is correctly set to Pageview but we need to filter the event by path. To do this, click the filter icon next to the step and filter on Path Name where the path value is /.

A funnel visualization won't appear at this point because a funnel must have more than one step.

Step 2 - User clicks SignUp button

To add the second step, click either of the Add funnel step buttons. Change the event to Autocapture since the event we're looking to make use of was one autocaptured by the PostHog JS SDK. Then, set a filter. When you click the filter icon this time, select the Elements tab and select the Text property.

For the filter value choose SignUp, which should be pre-populated based on the values that PostHog has already ingested from our testing.

As you populate this step, you'll see the funnel visualization appear.

Note: you could also have done a Pageview again here, filtered by a Path Name value of /auth.

Step 3 - User submits sign up form

For this step we want to track the sign up form submission. So, create a new step with an event of Autocapture and a first filter on the Event Type property (not be confused with the top-level event) with a value of "submit" for the form submission.

However, the above filter will track all form submissions. This may include forms other than the sign up form. So, add a second filter specifically identifying the sign up form based. To do this, select the Elements tab, choose CSS Selector, and set the selector value as [id="sign_up_form"] to identify the id attribute as having a value of sign_up_form.

Step 4 - User receives registration email

As noted in the table above, we don't presently have a way of tracking this because it happens on systems outside of our control. Remember, though, it may be that an email provider could integrate with PostHog to also track email events.

Step 5 - User clicks on link in email and logs into app

This represents successful completion of our sign up funnel. We added some custom code for this step earlier where a loggedIn event was captured. Of course, for a user to have successfully logged in it does also mean that the sign up has been successful.

So, add a new step to the funnel and select the loggedIn.

The funnel is now complete and we can see the journey of users through the sign up funnel, users that have dropped off, and users that have completed sign up.

You can adjust the options in the right-hand panel, if required. For example, you can change the orientation of the funnel visualization from left-to-right to top-to-bottom, the computation in the steps from Overall converstion to Relative to previous step, and the period of time the Funnel is calculated over.

Finally, you can save the Funnel, giving it a name of Signup Funnel, and add it to a Dashboard by clicking Save & add to dashboard.

Conclusion

In this tutorial, you've learned how to create a sign up flow with Next.js and Supabase Auth. You've then ensured all the necessary application events are being ingested into PostHog. This then allows you to define the sign up flow as a sign up Funnel so you can measure the success of the user journey and identify where users drop off.

Where next?

Here are a few examples of where you could explore next.

Use Actions instead of Events

We've made extensive use of Events within this tutorial. However, it can be beneficial to wrap events up into something called Actions. Actions let you group multiple events which can then be used within Insights, such as Funnels.

For example, in this tutorial we used an Event Type and a CSS Selector to track the sign up form submission. If we were to instead create an Action and call it Sign up form submitted this Action could be used within the Sign up Funnel and also easily reused within other Insights. So, why not take a look at creating some reusable Actions, update the existing Funnel to use them, and try creating some other Insights?

Track email sending

We were unable to track the email sending within this tutorial. How about exploring a way to add capture a signUpEmailSent event within PostHog when the verification email is sent?

There are a couple of options here:

Supabase uses a tool called GoTrue which does support webhook configuration for email events such as validate, signup or login. Why not get involved in the Supabase community and see if these events can be exposed via Supabase?
Turn on Enable Custom SMTP within Supabase and use a third-party email provider that exposes webhooks for email events?

Announcing the tru.ID CLI

Phil Leggetter — Wed, 03 Mar 2021 01:55:09 +0000

As a developer-first and API-first company, we prioritise tools that will make you, the developer, successful. Today we're excited to announce the tru.ID CLI: built on top of our public APIs, open sourced, and your go-to developer tool when building on the tru.ID platform.

Why a CLI?

Many of us spend a lot of time in the terminal, so a CLI enables you to work from where you already are. IDEs such as Visual Studio Code and Android Studio come with in-built terminals. But having a CLI also allows us to build integrations into existing development workflows, via scripts, outside of the IDE. For example, Xcode behaviours or integration into CI/CD workflows.

Using Oclif & Open Source

The tru.ID CLI is built upon the excellent oclif open CLI framework by Heroku. Oclif provides a foundation for CLI functionality such as subcommands, command arguments and flags, plugin support and lots of utilities that enable us to focus on features instead of building our own CLI framework.

If you'd like to see how we've used Oclif the tru.ID CLI is on GitHub. Within the GitHub repo you'll find two branches:

main for the latest stable release
canary if you'd like to try out the latest features

We'd love to hear what you think so please ask questions, share ideas and raise PRs on the tru-ID/cli repo.

Install and Setup the tru.ID CLI

For the moment the only installation option is via NPM so you'll need Node.js installed.

With Node.js installed you install the tru.ID CLI as follows:

$ npm install -g @tru_id/cli

Or, if you prefer Yarn:

$ yarn global add @tru_id/cli

To try out the latest features use @tru_id/cli@canary.

With the tru command installed, setup the CLI with the credentials you'll find within the tru.ID console.

$ tru setup:credentials {client_id} {client_secret} eu

eu is the region where your account data is stored and, at the time of this blog post, is the only region we have available (more coming soon).

You can now query the credit you have available using:

$ tru workspaces

And the output will be similar to:

credentials.client_id                data_residency balance.amount_available balance.currency created_at
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx EU             28                       API              2020-08-12T12:46:56+0000

Creating a tru.ID Project

Projects are configuration containers within the tru.ID platform and you'll normally have a one-to-one mapping of a tru.ID project to an application that you are developing (though you may also create a project per environment: dev, staging and prod). A key piece of configuration are the project credentials which contain a client_id and client_secret that you use to authenticate interactions with the tru.ID APIs.

You create projects using the CLI:

$ tru projects:create "My Awesome Project"

And you'll see output such as:

Creating Project "My Awesome Project"
Project configuration saved to "~/my_awesome_project/tru.json".

The tru.json file contains your project configuration including the project credentials. Don't check this into source control!

With a project created you can cd my_awesome_project so the CLI can read the tru.json file from the cwd and you have everything you need to fully utilise the tru.ID CLI.

Trying the tru.ID APIs

CLIs normally focus on platform management functionality, such as creating and managing projects, but we decided to also add commands to let you try out our products from the terminal. Of course, you can also try these out programmatically too.

SIMCheck

SIMCheck is an API that queries when the SIM card associated with a phone number last changed:

$ tru simchecks:create

With the output being similar to the following, which prompts for the phone number to be checked:

? Please enter the phone number you would like to SIMCheck +{phone_number}
Creating SIMCheck for +{phone_number}

    status: COMPLETED
    no_sim_change: true
    last_sim_change_at: 2017-01-26T07:16:57+0000

The no_sim_change value indicates that the SIM card hasn't changed within the last seven (7) days, and last_sim_change_at specifies the last change date (when I changed my mobile phone provider from giffgaff UK to EE UK).

PhoneCheck

PhoneCheck verifies that a phone number is associated with a SIM card within the mobile device. This is achieved via tru.ID's integration with MNOs (Mobile Network Operators) around the world. For a more in-depth look at how this works, check out the PhoneCheck integration guide. Of course, you can also try this out via our CLI:

$ tru phonechecks:create --workflow

The output of this command prompts for a phone number and also displays a QR code to scan on a mobile device. It also provides instructions to disable WiFi on the device, as part of the PhoneCheck workflow is to make a web request over the device's mobile data connection.

? Please enter the phone number you would like to PhoneCheck +{phone_number}
Creating PhoneCheck for +{phone_number}
PhoneCheck ACCEPTED
check_id: 76a36abb-8495-403a-9f71-531c80c6a26b
check_url: https://eu.api.tru.id/phone_check/v0.1/checks/76a36abb-8495-403a-9f71-531c80c6a26b/redirect
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █▄█  ██ ▄███ ▀▄▄ ▄▀█ ██ ▄  ▀██▀█▀▀  █  ▄ ██ ▄▄▄▄▄ █
█ █   █ █ ▄▀▄ █▄█▄█▀█████ ▄█ ██▄▄▄▄█▀▀█▀ █ ▀█▄▀▄ ██ █   █ █
█ █▄▄▄█ █▄ █▀  ▀▀▀   ▀▀  ▀█ ▄▄▄   ▄█▄▄   ▀ ▀▄▄▄▀▄██ █▄▄▄█ █
█▄▄▄▄▄▄▄█▄▀▄█▄█▄█▄█▄▀▄█▄█ ▀ █▄█ █▄█ ▀▄▀ ▀ ▀ ▀▄█ ▀▄█▄▄▄▄▄▄▄█
█    ▀▀▄▀▄▄▀▄▀▀█▄▄ ▀▄▄  ▀ ▄ ▄▄▄  ███ █▀██ ▀▀ ▀▀▄▄  ██ ▄▄▀▄█
███▀▄▀▄▄█▄ ▀   ▀██ ██▄▄▄▀ ▄▄██▀ █▄ ▀ ▀▀▄ ▄ ▀█ ▄  ▄████ █  █
█▀▄█ ▀▀▄█▀ ▄█▄▄ █▄█▄  █▄▄██ █▀▄▄ ▀ ▄▀▄   ▀▄▄▀▀ ▄▄█▄▀▄▀ █▄▄█
█▄██ ▄ ▄▄ ▄▀▀▀▀█ ▄▀██▄▄▀▀ ▄▄▄█ ▄▄ ██▄█ █▀ █ █ ▄█▀▀ ▄▀▀▀ █▀█
█▄▀▀▄██▄█▄▄▄  ▄▄▄ █▀██▄█ ▄ █▄█ ▄▄▄▄ ▀█▀▄▀▀▄▄▄▄▄  ▄ █ █▄██ █
█ ▀ ▄ ▀▄▄▀  █▄▀▀ ▄  ██▀█▀▄▀ ▄█ ▀██▀▄█▀▄ █▀▀█▀█▀  ▀▀▄▀▀▀█▀▀█
███ ▄▀ ▄ ▀  ▀▀ ██ ▄███  ▀ ▄▀▄ █▀██▄▄▀▀███ ▄ ▀▀ ▄▀ █▄█▄▀ █▀█
█▀▄ ▀██▄▀ █ ▀█ ▄▀▄ █ ▄  ▀███▄▄█▄█▄▄▄█▀▄▀█▀▀ ▄█  █▄▀▀█▄██▄ █
█▀▄██ ▄▄ ▄ █ ▀ ▄█▄   ▀█▀█▄ ▀█▀▀█▄▀ █▄▄ ▀███▄▄█ ██▄  ▀█▄█▄▄█
██▄▀  ▄▄▄ ▀▀ ▀█▀▀ ▄▄▄▀█▄█ ▄ ▄▄▄   █▄▀██▄▀▀█▄▄▀▄▄▀ ▄▄▄ ▀▀▀▀█
█ ▀ ▄ █▄█ ▀█▀ ▄▀▀ █▄██▀▀ █▀ █▄█ ▄▄ ▀█▀ ▄▄▀ ██▄▄▀▄ █▄█ ▀▄▀ █
██▀▀█ ▄▄  ██▄▄█▄ ▄█▀ ▀█ ▀█▄  ▄▄  ▄█▄▄ █  ▀▄▀██ ▄▄  ▄ ▄██ ▀█
█ ▄██ ▄▄ ███▀█▄█▄███ ▄    █▄▀█ █ ▀ ▄▀▀▄██▄▄▀█▀██▀█▀▄ █▀▄▄▀█
██▄   ▀▄█▀▄ ▄▀██▀  ▀ █▄▀ ▄▄█ ▀███ █ █  █▀▄█▄▄ █▄█▀█ ▄ ███▄█
█▄██▀ █▄█▄▄█ ▄█▀███ ▀██▀█▄█▄ ▄ ▄ ▀ █▀ █ ██▄▄█▀▀█▀▀▄▄▀█ ▀▀██
█▀▄█▄▄▄▄▄█  █ ██ ▄▀▄  ▄▀▀ ▀ ▄▄ █ ▀█▀ ▀█ █▄▀ ▀▀██▀ █▀▄█ ▀█▄█
█▀▄█ █▄▄▀ █▀▀ █▀  ▀▀██▄▀█▄▀▄▀▀▄██▄▀▀████ ▀ ██▄ ▀▄█▄▀▄ ▀██▄█
██  ▀▀▄▄▀ ▄ ▄██▄▀▀█▄▀ █ ▄▄▄     ▄█ ▄  ▀   █▄ ▄ ▀██ █ ██▄▄▀█
█▀▄▀▄█▀▄ ▀▀ █ ▄▀ █▀▀ ▄ █▄ ▄  █▀█▀▀ ▄████▀▄▀▀ ▀███▄ ▀██▄ ▄ █
█ ▀ ▀▀▄▄▄ ██▀▄▀   ▀█▀█ ▀▀█  ▄ ███▀▀▄▄▀ █▀▄█ ▄ █  █▀ ██▀▄  █
███████▄█▀▀▄ ▀▄█ ██ ▀ ▀██▄▀ ▄▄▄ ▀▀███▄  ▄█▀▄▀███▀ ▄▄▄ ▀▀ ██
█ ▄▄▄▄▄ ██ █ █▄█▀█  ▀ ███ ▄ █▄█ █▀▄▀█▀ ▄▄ ▄ ▄▀▄█▄ █▄█ █▀▄▀█
█ █   █ █▀ █▀▄ █▀█ ▀ ▄ █▀▄▀  ▄▄   ▀▀█▀██▄▀█▄▄▄█   ▄▄ ▄▀▄ ██
█ █▄▄▄█ █ █▄▄▄▀▀  ▄▄▄▀▄ ▀ ▀▀█▀██ ▄  ▀ █ ██▄██▄▀▄▀ █▀███▄█▀█
█▄▄▄▄▄▄▄█▄▄▄▄▄▄▄█▄▄██▄▄▄█████▄▄███▄▄▄██▄▄▄▄▄██▄▄▄██▄█▄▄▄███

Please ensure the mobile phone with the phone number +{phone_number} is disconnected from WiFi and is using your mobile data connection.

Then scan the QR code and navigate to the check_url.

Waiting for a PhoneCheck result... done

PhoneCheck Workflow result:
    status:  COMPLETED
    match:  true ✅

QR codes in the terminal. Pretty cool, huh!

As well as creating resources you can also query existing ones:

$ tru phonechecks:list 76a36abb-8495-403a-9f71-531c80c6a26b
check_id                             created_at               status    match charge_currency charge_amount
76a36abb-8495-403a-9f71-531c80c6a26b 2021-02-23T21:08:56+0000 COMPLETED true  API

You can also try out tru phonechecks:list with flags such as --search to add query conditions the API request, --filter to filter a result from the API, and --output to change the output format e.g. --output json.

SubscriberCheck

The CLI also supports SubscriberCheck, which runs a PhoneCheck but also includes a SIMCheck within the result. We'll leave trying that out to you, but here's the creation command that runs through the QR code workflow:

$ tru subscriberchecks:create --workflow

What Else Can the CLI Do?

Two other commands worth highlighting are oauth2 and coverage.

OAuth2

Our APIs use OAuth2 credentials and access tokens for authentication. But we know that sometimes you just want access to an access token without having to concatenate a project client_id and client_secret, Base 64 encode that value, make a request to the /token endpoint to create an access token, and then eventually getting to use it. So, the oauth2 command makes it a bit easier to create an access token when you're just trying things out.

Note: Running the following command from a directory that contains a tru.json project configuration file will use the credentials for the project. If you run the command without a tru.json in the cwd you'll use the credentials you supplied in the tru setup:credentials command.

$ tru oauth2:token

Then you just need to copy the access token and use it:

access_token
GXuXq1DKa2LdBikD0jC8DenJgJTdgPSONLC0TpYqIzQ.ko9hRxKojOYhSvWkUBsPtHNPSUtB5KMwCqw8_FjUW6c

You can also assign the output to a variable and use it either in a mobile client or to try things out via cURL:

$ TOKEN=$(tru oauth2:token --no-header)
$ curl -s -X GET \
-H "Authorization: Bearer $TOKEN" \
https://eu.api.tru.id/phone_check/v0.1/checks/76a36abb-8495-403a-9f71-531c80c6a26b
{"check_id":"76a36abb-8495-403a-9f71-531c80c6a26b","status":"COMPLETED","match":true,"charge_amount":1.00,"charge_currency":"API","created_at":"2021-02-23T21:08:56+0000","updated_at":"2021-02-23T21:09:26+0000","_links":{"self":{"href":"https://eu.api.tru.id/phone_check/v0.1/checks/76a36abb-8495-403a-9f71-531c80c6a26b"}}}%

Coverage

Coverage provides two endpoints and is thus a "topic" with two commands in the CLI.

coverage:country {country_code} allows you to query if the tru.ID platform has coverage for a given country. You can use either a phone number country code prefix:

$ tru coverage:country +44
product_name     network_id network_name currency amount
Phone Check      23410      O2 UK        API      1
Phone Check      23415      Vodafone UK  API      1
Phone Check      23420      3 UK         API      1
Phone Check      23430      EE UK        API      1
Sim Check        23410      O2 UK        API      1
Sim Check        23415      Vodafone UK  API      1
Sim Check        23420      3 UK         API      1
Sim Check        23430      EE UK        API      1
Subscriber Check 23410      O2 UK        API      1
Subscriber Check 23415      Vodafone UK  API      1
Subscriber Check 23420      3 UK         API      1
Subscriber Check 23430      EE UK        API      1

Or a two-letter alpha country code:

$ tru coverage:country CA
product_name network_id network_name currency amount
Phone Check  302220     Telus        API      1
Phone Check  302610     Bell         API      1
Phone Check  302720     Rogers       API      1

coverage:reach also performs a tru.ID platform coverage query but based on the IP address (IPv4 or IPv6) of the device:

$ tru coverage:reach 213.205.197.123
network_id network_name country_code supported_products
23430      EE UK        GB           Phone Check,Sim Check,Subscriber Check

Try out the CLI and let us know what you think

In this post we've covered a number of the main commands but there's more that the CLI offers. Either install the tru.ID CLI (npm install -g @tru_id/cli) and tru --help to find out more, or take a look at the CLI Reference docs to see what else is possible.

We believe the tru.ID CLI offers a good first developer experience of our platform. But we'd love to know what you think via feedback@tru.id.

If you haven't already, signup for a tru.ID account, follow @_tru_id on Twitter and join our mission to reimagine mobile authentication.