https://typedwebhook.tools

Sponsored by Inngest

A webhook testing tool which automatically creates types for incoming requests. Any incoming request which is valid JSON is automatically converted to:

• TypeScript
• Cue
• JSON Schema

Here's the website. It's free to use. Knock yourself out!

Why?

Webhooks are great! But, to use them you almost always need to generate types for the request data. Why not have that done automatically for you?

At Inngest we love events. And types. So much that our service allows you to build & deploy serverless functions that run whenever events are received (like webhooks).

We hope this tool — and Inngest — is useful for you and saves you time as a developer ✨

Example types

{
  "name": "Test event",
  "data": {
    "id": 1,
    "name": "Tester McTestFace",
    "by": "Inngest",
    "at": "2022-02-21T21:19:05.529Z"
  },
  "user": {
    "email": "[email protected]"
  },
  "ts": 1645478345529
}

export interface Event {
  name: string;
  data: {
    by: string;
    at: string;
    id: number;
    name: string;
  };
  user: {
    email: string;
  };
  ts: number;
};

{
  data: {
    id:   int
    name: string
    by:   string
    at:   string
  }
  user: {
    email: string
  }
  ts:   int
  name: string
}

{
  "properties":{
    "data":{
      "properties":{
        "at":{
          "type":"string"
        },
        "by":{
          "type":"string"
        },
        "id":{
          "type":"integer"
        },
        "name":{
          "type":"string"
        }
      },
      "required":[
        "id",
        "name",
        "by",
        "at"
      ],
      "type":"object"
    },
    "name":{
      "type":"string"
    },
    "ts":{
      "type":"integer"
    },
    "user":{
      "properties":{
        "email":{
          "type":"string"
        }
      },
      "required":[
        "email"
      ],
      "type":"object"
    }
  },
  "required":[
    "data",
    "user",
    "ts",
    "name"
  ],
  "type":"object"
}

Architecture

There are three main components to this app:

• The backend, hosted using Cloudflare workers.
• The frontend, built using SvelteKit.
• The type generator, built using Inngest's event schema packages and ran using webassembly.

The backend runs on Cloudflare workers. It accepts requests to create webhook endpoints; to susbcribe to webhook results via websockets; and accepts requests to a webhook URL to record the webhook data.

Each webhook has it own unique UUID. While the chance of collision is extremely low, webhooks are also created with a shared secret - transmitted only once when the webhook is created. This secret must be supplied when connecting via websockets to receive any requests sent to the URL. This means that:

• Webhooks are private
• Webhooks are transient (no data is stored using this service; they're proxied directly to the browser)
• Webhooks are secure

Type creation

The fun stuff! To create types from plain ol' JSON objects we use the following pipeline:

1. Convert the JSON to a Cue type. We do this for you. Cue is fantastic. It's both type definitions and constraints in one.
2. Use our Cue-to-Typescript package we made. This was fun. It also properly generates enums, interfaces, etc. according to best practices.
3. Use cue's JSON schema generation capabilities.

You might be wondering - hey, this is in go, how does this run? If you guessed webassembly, give yourself a lil pat on the back! We shift this to the browser because we dont want to see your data. We believe that utilities like this should be free (this is) and should be private (hey, this is too!). If we ran this on a server then, well, we'd have to send your event to a backend. And, as explained above, the current backend runs in Cloudflare and literally proxies the request to your websocket connection.

In the future maybe we rewrite this as a go app and do this as we process the request. Who knows. This works, and it only took us a couple days to make.

Hacking away & contributing

PRs are welcome! As are issues. If you're interested in hacking on the type creation stuff, that repo is here: https://github.com/inngest/event-schemas. PRs also welcome to that repo.

Development

# Install dependencies
$ npm install
# Start local development server with live reload
$ npm run dev
# Run tests
$ npm test
# Run type checking
$ npm run types:check

License

GPL, my friend. It's open-source, and should stay that way.