Express SDK

@subdomainto/express v0.1 supports Express 4.21 through 5.x on Node.js 20+. It is server-only and builds on @subdomainto/node.

Installation

npm install @subdomainto/express

Create the client

import { createSubdomainToClient } from '@subdomainto/express';

const client = createSubdomainToClient();
const domain = await client.domains.create('portal.customer.com', 'customer-42-domain');

The factory reads SUBDOMAINTO_API_KEY and optional SUBDOMAINTO_BASE_URL. You may instead pass the same options as the Node.js client.

Verify webhooks

Express must preserve the raw JSON body before the subdomain.to middleware:

import express from 'express';
import { subdomainToWebhook } from '@subdomainto/express';

const app = express();

app.post(
  '/webhooks/subdomainto',
  express.raw({ type: 'application/json' }),
  subdomainToWebhook(),
  (request, response) => {
    const event = request.subdomainToEvent;
    response.sendStatus(204);
  },
);

The middleware reads SUBDOMAINTO_WEBHOOK_SECRET, accepts an optional tolerance, places the verified event on request.subdomainToEvent, and returns 400 for an invalid delivery. A parsed JSON body cannot be verified.