feat: dynamic webhook URL per session

[vgpastor]

Summary

Implements the feature proposed in #34 — dynamic webhook URL configuration per session, without requiring environment variables or server restarts.

Changes

src/sessions.js

• setupSession(sessionId, options) now accepts an optional options.webhookUrl parameter
• Webhook URL is stored in-memory on the client object (client.webhookUrl)
• initializeEvents uses a getWebhookUrl() closure that resolves at call time: client.webhookUrl → env session var → BASE_WEBHOOK_URL
• Webhook URL is preserved across session restarts and reloads
• Webhook URL is persisted to disk (session-{id}/webhook_config.json) so it survives server restarts
• restoreSessions loads persisted webhook config when restoring sessions
• New exported functions: setSessionWebhook(), getSessionWebhook()

src/controllers/sessionController.js

• startSession reads optional webhookUrl from req.body (works with both GET for backward compat and POST with JSON body)
• New setWebhook controller to update webhook URL at runtime
• New getWebhook controller to retrieve current webhook URL and its source (runtime, env_session, env_global, none)

src/routes.js

• Added POST /session/start/:sessionId (accepts webhookUrl in body) alongside existing GET route
• Added PUT /session/setWebhook/:sessionId — update webhook URL at runtime
• Added GET /session/getWebhook/:sessionId — get current webhook URL and source

Backward Compatibility

• Zero breaking changes: GET /session/start/:sessionId still works exactly as before
• If no webhookUrl is provided, behavior is identical to current: env session var → BASE_WEBHOOK_URL
• All existing environment variable configuration continues to work as fallback

Persistence

Webhook URLs configured via API are persisted to session-{id}/webhook_config.json inside the session folder. This means:

• Server restarts: When AUTO_START_SESSIONS=true, restored sessions will reload their webhook URLs from disk
• Session restarts/reloads: Webhook URL is preserved in-memory and on disk
• Session terminate: The webhook_config.json is deleted along with the session folder
• Clearing webhook: Sending empty/null webhookUrl removes the config file, falling back to env vars

Usage Examples

Start session with webhook:

curl -X POST http://localhost:3000/session/start/my-session \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl": "https://my-n8n.com/webhook/abc123"}'

Update webhook URL at runtime:

curl -X PUT http://localhost:3000/session/setWebhook/my-session \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl": "https://my-n8n.com/webhook/new-url"}'

Check current webhook:

curl http://localhost:3000/session/getWebhook/my-session
# {"success":true,"webhookUrl":"https://...","source":"runtime"}

Priority Resolution

1. client.webhookUrl (set via API, persisted to disk)  ← NEW
2. process.env[SESSIONID_WEBHOOK_URL]                  ← existing
3. BASE_WEBHOOK_URL                                    ← existing

Closes #34

[vgpastor]

n8n Integration — How we plan to use this feature

We maintain n8n-nodes-wwebjs-api, a community n8n node that integrates with this API. We've already prepared a PR on our side that adds webhook management operations using the endpoints proposed here.

Usage from n8n

Once this PR is merged, n8n users will be able to:

1. Start a session with a webhook URL

POST /session/start/{sessionId}
Body: { "webhookUrl": "https://my-n8n.com/webhook/abc123" }

This eliminates the need to configure BASE_WEBHOOK_URL or per-session env vars before starting sessions.

2. Update the webhook at runtime

PUT /session/setWebhook/{sessionId}
Body: { "webhookUrl": "https://my-n8n.com/webhook/new-endpoint" }

Useful when n8n webhook URLs change (e.g., after redeployment) — no server restart needed.

3. Query the current webhook configuration

GET /session/getWebhook/{sessionId}
→ { "success": true, "webhookUrl": "...", "source": "runtime" }

Helps users debug and verify their webhook setup directly from n8n.

Why this matters for n8n users

Currently, connecting n8n ↔ wwebjs-api requires manually setting environment variables and restarting the API server whenever webhook URLs change. This PR enables a fully self-service workflow where the n8n node handles webhook registration automatically, significantly reducing setup friction.

The persistence feature (webhook_config.json) is especially important — it means that after a server restart, sessions automatically reconnect with the correct webhook URL without user intervention.

Looking forward to seeing this merged! 🙌

[vgpastor]

Correction: the link to our n8n-side PR is vgpastor/n8n-nodes-wwebjs-api#4.