feat: dynamic webhook URL per session by vgpastor · Pull Request #107 · avoylenko/wwebjs-api

vgpastor · 2026-02-19T12:58:32Z

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

- setupSession now accepts an optional webhookUrl parameter - Store webhookUrl on client object for runtime access - initializeEvents uses client.webhookUrl with fallback to env vars - Add setSessionWebhook function to update webhook URL at runtime - Add getSessionWebhook function to retrieve current webhook URL Closes avoylenko#34

- startSession now reads optional webhookUrl from request body - Accepts both GET (backward compat) and POST with JSON body - Add setWebhook endpoint to update webhook URL at runtime - Add getWebhook endpoint to retrieve current webhook URL and source

- Add POST /session/start/:sessionId (accepts webhookUrl in body) - Keep GET /session/start/:sessionId for backward compatibility - Add PUT /session/setWebhook/:sessionId - Add GET /session/getWebhook/:sessionId

- Save webhookUrl to session-{id}/webhook_config.json on set - Load webhookUrl from disk on session restore (restoreSessions) - Delete webhook_config.json when session folder is deleted - Webhook URL survives server restarts when AUTO_START_SESSIONS=true

- Add 'Set Webhook' operation: configure webhook URL for active session at runtime - Add 'Get Webhook' operation: retrieve current webhook URL and its source - Add optional 'Webhook URL' option to 'Start' session operation - Start uses POST when webhookUrl provided (requires wwebjs-api v1.35+) - Graceful fallback: Start uses GET when no webhookUrl (backward compat) These operations correspond to the upstream PR avoylenko/wwebjs-api#107 which adds dynamic webhook URL support to the REST API. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vgpastor · 2026-02-19T13:09:30Z

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 · 2026-02-19T13:09:36Z

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

vgpastor · 2026-02-28T19:32:28Z

@avoylenko can you see this PR? Thanks!!

avoylenko · 2026-02-28T19:46:52Z

@vgpastor thank you for your work. Gonna do that next week, at this time main occupation takes all free time.

Copilot

Pull request overview

Adds per-session webhook URL configuration so sessions can be started and updated with a webhook URL at runtime, with persistence across restarts (via a session-scoped config file), addressing the “set webhook during session creation” request from #34.

Changes:

Extends session setup to accept an optional webhookUrl, stores it on the client, and resolves webhook destination dynamically at event-trigger time.
Persists/restores per-session webhook configuration to/from session-{id}/webhook_config.json.
Adds/extends HTTP endpoints to start sessions via POST with JSON body and to set/get webhook URL at runtime.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
`src/sessions.js`	Adds webhook config persistence helpers, runtime get/set helpers, and updates event dispatch to resolve webhook URL dynamically.
`src/controllers/sessionController.js`	Accepts `webhookUrl` during session start and adds controllers to set/get webhook configuration at runtime.
`src/routes.js`	Adds routes for POST start, setWebhook, and getWebhook endpoints.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+    if (fs.existsSync(configPath)) {
+      const data = JSON.parse(fs.readFileSync(configPath, 'utf8'))
+      if (data && data.webhookUrl) {
+        logger.info({ sessionId, webhookUrl: data.webhookUrl }, 'Webhook config loaded from disk')


+    // Store custom webhook URL on client if provided via API or loaded from disk
+    if (options.webhookUrl) {
+      client.webhookUrl = options.webhookUrl
+      logger.info({ sessionId, webhookUrl: options.webhookUrl }, 'Custom webhook URL configured for session')


+  client.webhookUrl = webhookUrl || null
+  // Persist to disk so it survives server restarts
+  saveWebhookConfig(sessionId, webhookUrl)
+  logger.info({ sessionId, webhookUrl: webhookUrl || '(cleared, using default)' }, 'Session webhook URL updated')


+    // Read optional webhookUrl from body (works for both GET with empty body and POST with JSON)
+    const options = {}
+    if (req.body && req.body.webhookUrl) {
+      options.webhookUrl = req.body.webhookUrl
+    }


+    const { webhookUrl } = req.body || {}
+    const result = setSessionWebhook(sessionId, webhookUrl)
+    if (!result.success) {


@@ -49,6 +50,8 @@ sessionRouter.get('/terminate/:sessionId', middleware.sessionNameValidation, ses
 sessionRouter.get('/terminateInactive', sessionController.terminateInactiveSessions)
 sessionRouter.get('/terminateAll', sessionController.terminateAllSessions)
 sessionRouter.get('/getPageScreenshot/:sessionId', middleware.sessionNameValidation, sessionController.getPageScreenshot)
+sessionRouter.put('/setWebhook/:sessionId', middleware.sessionNameValidation, sessionController.setWebhook)
+sessionRouter.get('/getWebhook/:sessionId', middleware.sessionNameValidation, sessionController.getWebhook)


avoylenko · 2026-06-25T08:09:54Z

@vgpastor lease take a look when you have free time. Copilot suggestions seems legit.

vgpastor added 4 commits February 19, 2026 13:26

feat: add routes for dynamic webhook management

78df5fe

- Add POST /session/start/:sessionId (accepts webhookUrl in body) - Keep GET /session/start/:sessionId for backward compatibility - Add PUT /session/setWebhook/:sessionId - Add GET /session/getWebhook/:sessionId

vgpastor mentioned this pull request Feb 19, 2026

feat: add webhook management operations to Session resource vgpastor/n8n-nodes-wwebjs-api#4

Open

3 tasks

avoylenko requested a review from Copilot June 23, 2026 18:09

Copilot started reviewing on behalf of avoylenko June 23, 2026 18:09 View session

Copilot AI reviewed Jun 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: dynamic webhook URL per session#107

feat: dynamic webhook URL per session#107
vgpastor wants to merge 4 commits into
avoylenko:mainfrom
vgpastor:feat/dynamic-webhook-url

vgpastor commented Feb 19, 2026 •

edited

Loading

Uh oh!

vgpastor commented Feb 19, 2026

Uh oh!

vgpastor commented Feb 19, 2026

Uh oh!

vgpastor commented Feb 28, 2026

Uh oh!

avoylenko commented Feb 28, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

avoylenko commented Jun 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

vgpastor commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Backward Compatibility

Persistence

Usage Examples

Priority Resolution

Uh oh!

vgpastor commented Feb 19, 2026

n8n Integration — How we plan to use this feature

Usage from n8n

Why this matters for n8n users

Uh oh!

vgpastor commented Feb 19, 2026

Uh oh!

vgpastor commented Feb 28, 2026

Uh oh!

avoylenko commented Feb 28, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

avoylenko commented Jun 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vgpastor commented Feb 19, 2026 •

edited

Loading