Configuration

Environment variables

Variable	Description	Default
QUEUEBASE_API_URL	Queuebase API endpoint	http://localhost:3847 (dev)
QUEUEBASE_API_KEY	API key for production	—
QUEUEBASE_CALLBACK_URL	Your app’s webhook endpoint	http://localhost:3000/api/queuebase
QUEUEBASE_WEBHOOK_SECRET	Secret for webhook signature verification	—

Webhook verification

If QUEUEBASE_WEBHOOK_SECRET is set, the handler automatically verifies HMAC-SHA256 signatures on incoming requests (via the X-Queuebase-Signature header) and rejects unsigned or invalid requests.

In development this is optional. In production you should always set a webhook secret to prevent unauthorized job executions.

defineConfig

The defineConfig helper provides defaults and reads from environment variables. It’s available from both @queuebase/nextjs and @queuebase/node.

import { defineConfig } from "@queuebase/nextjs"; // or @queuebase/node

export const config = defineConfig({
  jobsDir: "./src/jobs",
  callbackUrl: "http://localhost:3000/api/queuebase",
  apiUrl: "http://localhost:3847",
  apiKey: undefined,
});

Option	Type	Description	Default
jobsDir	string	Directory containing job definitions	./src/jobs
callbackUrl	string	Webhook endpoint URL	QUEUEBASE_CALLBACK_URL env var, or http://localhost:3000/api/queuebase (Next.js only)
apiUrl	string	Queuebase API endpoint	QUEUEBASE_API_URL env var, or auto-detected by NODE_ENV
apiKey	string	API key	QUEUEBASE_API_KEY env var

Environment variables always take precedence over values passed to defineConfig.

Note

The Next.js SDK defaults callbackUrl to http://localhost:3000/api/queuebase when no value is provided. The Node.js SDK has no default — you must set it via QUEUEBASE_CALLBACK_URL or pass it explicitly, since your server may run on any port or path.

Callback URL validation

In production, callback URLs are validated to prevent server-side request forgery (SSRF). The API rejects URLs targeting:

• localhost and loopback addresses (127.x.x.x, [::1])
• Private IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
• Non-HTTP schemes (file://, ftp://, data:, etc.)

Any public HTTP or HTTPS URL is accepted. This validation applies to both the SDK enqueue endpoint and the dashboard project settings.

Note

The local dev server (queuebase dev) does not enforce these restrictions — localhost callbacks are expected during development.

Request limits

The production API enforces the following size limits:

Limit	Value	Response
Request body	10MB	413 Payload Too Large
Job payload field	1MB	400 Bad Request

If your job data exceeds 1MB, store it externally (e.g., in S3 or your database) and pass a reference as the payload instead.