subdomain.to for Express

@subdomainto/express connects Express applications to the subdomain.to custom domains API. It provides a server-side client factory for customer domain onboarding and middleware that verifies signed webhooks from the untouched request body.

Installation

npm install @subdomainto/express

The package supports Express 4.21 through 5.x and builds on the typed @subdomainto/node SDK.

Create the API 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 from the server environment. You can also pass the Node.js client options directly.

Verify Express webhooks

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

const app = express();

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

Apply express.raw() before the webhook middleware. Parsing the JSON first changes the signed payload and prevents safe verification. The middleware reads SUBDOMAINTO_WEBHOOK_SECRET, validates the HMAC signature and timestamp, then stores the verified event on request.subdomainToEvent.

Documentation

Read the complete Express SDK guide, the custom domains API documentation, or open an issue in the JavaScript SDK repository.

License

MIT