> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Use Ruba with Express
> Attach Ruba checkout, portal, and webhook handlers to Express routes
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
## Install the middleware
Add the Express adapter and Zod:
```bash Terminal theme={"system"}
npm install zod @getruba/express
```
```bash Terminal theme={"system"}
yarn add zod @getruba/express
```
```bash Terminal theme={"system"}
pnpm add zod @getruba/express
```
```bash Terminal theme={"system"}
bun add zod @getruba/express
```
## Create the checkout entry route
Mount `Checkout` on a `GET` route. The middleware resolves the checkout and sends the buyer to it.
```typescript theme={"system"}
import express from "express";
import { Checkout } from "@getruba/express";
const app = express();
app.get(
"/checkout",
Checkout({
accessToken: "xxx", // Or set an environment variable to RUBA_ACCESS_TOKEN
successUrl: process.env.SUCCESS_URL,
returnUrl: "https://myapp.com", // An optional URL which renders a back-button in the Checkout
server: "sandbox", // Use sandbox if you're testing Ruba - omit the parameter or pass 'production' otherwise
theme: "dark", // Enforces the theme - System-preferred theme will be set if left omitted
})
);
```
### Inputs accepted by the checkout route
| Query value | Use |
| -------------------- | ---------------------------------------------------- |
| `products` | One product ID or the product selection for checkout |
| `customerId` | Optional Ruba customer identity |
| `customerExternalId` | Optional identity from your own application |
| `customerEmail` | Optional buyer email prefill |
| `customerName` | Optional buyer name prefill |
| `metadata` | Optional URL-encoded JSON metadata |
For example, `?products=123&customerExternalId=user_42` selects a product and ties the session to your application identity.
## Create the account-management route
Return the Ruba customer ID for the current application user. The middleware then opens that customer's portal.
```typescript theme={"system"}
import express from "express";
import { CustomerPortal } from "@getruba/express";
const app = express();
app.get(
"/portal",
CustomerPortal({
accessToken: "xxx", // Or set an environment variable to RUBA_ACCESS_TOKEN
getCustomerId: (event) => "", // Function to resolve a Ruba Customer ID
returnUrl: "https://myapp.com", // An optional URL which renders a back-button in the Customer Portal
server: "sandbox", // Use sandbox if you're testing Ruba - omit the parameter or pass 'production' otherwise
})
);
```
## Receive signed events
Mount `Webhooks` after JSON parsing. It validates the Ruba signature before invoking your callback.
```typescript theme={"system"}
import express from 'express'
import { Webhooks } from "@getruba/express";
const app = express()
app
.use(express.json())
.post('/ruba/webhooks', Webhooks({
webhookSecret: process.env.RUBA_WEBHOOK_SECRET!,
onPayload: async (payload) => /** Handle payload */,
}))
```
### Choose callback granularity
Use `onPayload` as a catch-all or register callbacks around the domain your application owns:
| Domain | Available callbacks |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Checkout | `onCheckoutCreated`, `onCheckoutUpdated` |
| Orders and refunds | `onOrderCreated`, `onOrderPaid`, `onOrderRefunded`, `onRefundCreated`, `onRefundUpdated` |
| Subscriptions | `onSubscriptionCreated`, `onSubscriptionUpdated`, `onSubscriptionActive`, `onSubscriptionCanceled`, `onSubscriptionRevoked`, `onSubscriptionUncanceled` |
| Catalog | `onProductCreated`, `onProductUpdated`, `onBenefitCreated`, `onBenefitUpdated` |
| Entitlements | `onBenefitGrantCreated`, `onBenefitGrantUpdated`, `onBenefitGrantRevoked` |
| Customers | `onCustomerCreated`, `onCustomerUpdated`, `onCustomerDeleted`, `onCustomerStateChanged` |
| Organization | `onOrganizationUpdated` |