GitToken Express API Middleware

0.2.22 verified Sat Apr 25 auth: no javascript

Express middleware for validating GitHub webhook payloads using GitToken's Ethereum-based token system (v0.2.x). Provides HMAC signature verification with the webhook secret stored on-chain via ERC20 tokens. Key differentiator: integrates blockchain-based authorization directly into webhook handling, enabling token-gated CI/CD pipelines. Compatible with Express 4.x. Not suitable for non-GitHub webhooks or stateless applications. Release cadence: monthly updates.

Common errors

error TypeError: gittokenApiMiddleware is not a function ↓

cause Default import mismatch when using CommonJS

fix

Use const { default: gittokenApiMiddleware } = require('gittoken-api-middleware');

error Invalid webhook signature ↓

cause Raw body not passed to middleware correctly

fix

Ensure express.raw() is used before middleware and body is JSON

Warnings

gotcha Middleware requires raw body to be parsed after the middleware, not before ↓

fix Use express.raw() or body-parser with verify option to keep raw buffer

deprecated Version 0.x may change API without notice ↓

fix Pin exact version in package.json

Install

npm install gittoken-api-middleware

yarn add gittoken-api-middleware

pnpm add gittoken-api-middleware

Imports

gittokenApiMiddleware

wrong

const gittokenApiMiddleware = require('gittoken-api-middleware').default

correct

import gittokenApiMiddleware from 'gittoken-api-middleware'

ESM default export; require() needs .default

Quickstart

Sets up Express server with GitToken middleware validating GitHub webhooks using on-chain secret.

import express from 'express';
import gittokenApiMiddleware from 'gittoken-api-middleware';

const app = express();
const contractAddress = process.env.GTK_CONTRACT_ADDRESS ?? '0x...';
const accountKey = process.env.GTK_ACCOUNT_KEY ?? '';

app.post('/webhook', express.raw({type: 'application/json'}), gittokenApiMiddleware({ contractAddress, accountKey }), (req, res) => {
  const payload = JSON.parse(req.body);
  console.log('Valid webhook:', payload);
  res.status(200).end();
});

app.listen(3000, () => console.log('Server running'));