Feat(webhook_listeners): add auth tokens to webhook call #55790

janepie · 2025-10-15T13:58:28Z

Summary

Needed for Windmill integration.

This code adds an option to ask for authentication tokens when registering a webhook. The requested tokens will be added to the dispatched request to the defined endpoint.

All tokens generated with this have a lifetime of 1 hour and will be deleted after that in a background job every 5 min.

Tokens can be requested in the tokenNeeded parameter, which accepts listed values in the two fields "user_ids" and "user_roles".
"user_ids" is a list of user uids for which tokens are needed, "user_roles" is a list of roles (users not defined by their ID but by the role they have in the webhook event) for which tokens can be included. Possible roles: "owner" for the user creating the webhook, "trigger" for the user triggering the webhook call.

Checklist

Code is properly formatted
Sign-off message is added to all commits
Tests (unit, integration, api and/or acceptance) are included
Screenshots before/after for front-end changes
Documentation (manuals or wiki) has been updated or is not required
Backports requested where applicable (ex: critical bugfixes)
Labels added where applicable (ex: bug/enhancement, 3. to review, feature component)
Milestone added for target branch/version (ex: 32.x for stable32)

julien-nc

From you branch, at the top of server, you can run

composer i
# you might wanna revert what it does to lib/composer
git checkout ./lib/composer/
composer run cs:check ./apps/webhook_listeners/lib
# or if you have Php 8.4 like me and it's refused by php-cs
PHP_CS_FIXER_IGNORE_ENV=1 composer run cs:check ./apps/webhook_listeners/lib
# and if you want to fix the syntax issues:
composer run cs:fix ./apps/webhook_listeners/lib

(for later) To implement the token expiration mechanism you might need a new table where you store

the token ID
the webhook ID
if needed, the token creation timestamp

apps/webhook_listeners/lib/BackgroundJobs/WebhookCall.php

apps/webhook_listeners/lib/Controller/WebhooksController.php

apps/webhook_listeners/lib/Db/WebhookListener.php

oleksandr-nc · 2025-10-27T08:32:19Z

Who will revoke generated token once it is not needed? Will we revoke it in the server repo or in the Windmill integration app itself?

Another question related to previous: If the token was generated for user bob first time, and then second time the flow was triggered - should we create a new token for user bob or update the olds token expiration time?

julien-nc · 2025-10-27T09:02:24Z

@oleksandr-nc

Who will revoke generated token once it is not needed?

IMO the tokens should be revoked by a background job in webhook_listeners.

should we create a new token for user bob or update the olds token expiration time?

I think it's clearer and cleaner if we have independent tokens for each webhook "call". If the token generated for the first run leaks for some reason, it's bad if we make it live longer.

oleksandr-nc · 2025-10-27T09:11:37Z

IMO the tokens should be revoked by a background job in webhook_listeners.

This definetly should be added as a comment to the code.

julien-nc · 2025-10-27T09:13:32Z

Yep, this PR is still WIP. This is planned.

janepie · 2025-11-20T14:42:30Z

Sorry for all the change requests but this is quite a big PR.

No worries, thanks for reviewing so thoroughly! I think I got everything

apps/webhook_listeners/lib/Service/TokenService.php

marcelklehr · 2025-11-20T15:02:53Z

apps/webhook_listeners/lib/Db/EphemeralTokenMapper.php

+		$this->logger->debug('Invalidating ephemeral webhook tokens older than ' . date('c', $olderThan), ['app' => 'webhook_listeners']);
+		foreach ($tokensToDelete as $token) {
+			$this->tokenMapper->invalidate($this->tokenMapper->getTokenById($token->getTokenId())->getToken()); // delete token itself
+			$this->deleteByTokenId($token->getTokenId()); // delete db row in webhook_tokens


Error handling is missing here, I think. What if the token doesn't exist anymore in either table? The other tokens should still be deleted. Also, the getOlderThan could fail, I think

Hmm if it's failing to delete in the authtokens table, should it stay in the second table or not?

getOlderThan is a db query, what kind of failing are you thinking of?

Query failure. All db queries can fail with a DB Exception. That should always be handled, IMO

apps/webhook_listeners/lib/Db/EphemeralToken.php

Signed-off-by: Jana Peper <[email protected]>

marcelklehr · 2025-11-20T15:53:30Z

apps/webhook_listeners/lib/Db/EphemeralTokenMapper.php

+			$tokensToDelete = $this->getOlderThan($olderThan);
+		}
+		catch(Exception $e){
+			$this->logger->error('Webhook token deletion failed: ' . $e->getMessage(), ['exception' => $e]);


return, please :)

come-nc · 2025-11-24T08:23:14Z

apps/webhook_listeners/lib/BackgroundJobs/WebhookCall.php

 		$client = $this->clientService->newClient();
+
+		// adding Ephemeral auth tokens to the call
+		$data['tokens'] = $this->tokenService->getTokens($webhookListener, $data['user']['uid']);


$data['user'] may be null if an event is triggered from a public page.

Suggested change

$data['tokens'] = $this->tokenService->getTokens($webhookListener, $data['user']['uid']);

$data['tokens'] = $this->tokenService->getTokens($webhookListener, $data['user']['uid'] ?? null);

Something like that would work, if getTokens supports getting null as second parameter.

come-nc · 2025-11-24T08:29:51Z

apps/webhook_listeners/lib/Db/EphemeralTokenMapper.php

+		$this->logger->debug('Invalidating ephemeral webhook tokens older than ' . date('c', $olderThan), ['app' => 'webhook_listeners']);
+		foreach ($tokensToDelete as $token) {
+			try {
+				$this->tokenMapper->invalidate($this->tokenMapper->getTokenById($token->getTokenId())->getToken()); // delete token itself


Suggested change

$this->tokenMapper->invalidate($this->tokenMapper->getTokenById($token->getTokenId())->getToken()); // delete token itself

$this->tokenMapper->delete($this->tokenMapper->getTokenById($token->getTokenId())); // delete token itself

come-nc · 2025-11-24T08:33:58Z

apps/webhook_listeners/lib/Service/TokenService.php

+						];
+						break;
+					default:
+						$this->logger->error('Webhook token creation for user role ' . $function . ' not defined. ' . $e->getMessage(), ['exception' => $e]);


There is no $e object in this context or did I miss something?

come-nc · 2025-11-24T08:35:08Z

apps/webhook_listeners/lib/Service/TokenService.php

+			}
+		}
+		if (isset($tokenNeeded['user_roles'])) {
+			foreach ($tokenNeeded['user_roles'] as $function) {


Suggested change

foreach ($tokenNeeded['user_roles'] as $function) {

foreach ($tokenNeeded['user_roles'] as $user_role) {

The namings $function and $functionId in this loop are quite confusing.

come-nc · 2025-11-24T08:38:00Z

apps/webhook_listeners/lib/Service/TokenService.php

+		// We need the getToken() method to be able to send the token out.
+		// That method is only available in PublicKeyToken which is returned by generateToken
+		// but not declared as such, so we have to check the type here
+		if (!($deviceToken instanceof PublicKeyToken)) { // type needed for the getToken() function
+			throw new \Exception('Unexpected token type');
+		}


Suggested change

// We need the getToken() method to be able to send the token out.

// That method is only available in PublicKeyToken which is returned by generateToken

// but not declared as such, so we have to check the type here

if (!($deviceToken instanceof PublicKeyToken)) { // type needed for the getToken() function

throw new \Exception('Unexpected token type');

}

This is not true anymore, only getId is used and it’s part of the public interface.

Signed-off-by: Jana Peper <[email protected]>

janepie force-pushed the feat/webhook-tokens branch from e804cd1 to 5b188b6 Compare October 15, 2025 14:10

julien-nc reviewed Oct 15, 2025

View reviewed changes

janepie force-pushed the feat/webhook-tokens branch 2 times, most recently from 33585c0 to 78ea408 Compare October 16, 2025 13:47

janepie changed the title ~~Feat/webhook tokens~~ Feat: add auth tokens to webhook call Oct 17, 2025

janepie force-pushed the feat/webhook-tokens branch from 78ea408 to 8dae570 Compare October 17, 2025 14:24

janepie requested review from marcelklehr and oleksandr-nc October 17, 2025 14:26

janepie force-pushed the feat/webhook-tokens branch from 8dae570 to 12747b1 Compare October 17, 2025 14:27

janepie changed the title ~~Feat: add auth tokens to webhook call~~ Feat(webhook_listeners): add auth tokens to webhook call Oct 17, 2025

janepie force-pushed the feat/webhook-tokens branch from 12747b1 to 8572f9a Compare October 17, 2025 14:47

janepie force-pushed the feat/webhook-tokens branch 2 times, most recently from 0c0a98a to 7847d3b Compare October 30, 2025 16:57

janepie force-pushed the feat/webhook-tokens branch 2 times, most recently from 2d030cc to f53ad98 Compare November 12, 2025 11:31

janepie added this to the Nextcloud 33 milestone Nov 12, 2025

janepie force-pushed the feat/webhook-tokens branch 2 times, most recently from 647a122 to a6c77a7 Compare November 12, 2025 12:32

janepie added enhancement feature: webhooks labels Nov 12, 2025

janepie requested a review from julien-nc November 12, 2025 12:35

janepie force-pushed the feat/webhook-tokens branch 5 times, most recently from 0ff523e to 954d099 Compare November 12, 2025 14:18

marcelklehr reviewed Nov 20, 2025

View reviewed changes

apps/webhook_listeners/lib/Service/TokenService.php Show resolved Hide resolved

marcelklehr reviewed Nov 20, 2025

View reviewed changes

apps/webhook_listeners/lib/Service/TokenService.php Outdated Show resolved Hide resolved

marcelklehr reviewed Nov 20, 2025

View reviewed changes

apps/webhook_listeners/lib/Db/EphemeralToken.php Show resolved Hide resolved

janepie force-pushed the feat/webhook-tokens branch from 7f2528e to 0d081b6 Compare November 20, 2025 15:23

janepie added 15 commits November 20, 2025 16:24

feat: add token array to webhook definition and db entries

71bd9ea

Signed-off-by: Jana Peper <[email protected]>

feat: add tokens in the webhook call data

d2bcf54

Signed-off-by: Jana Peper <[email protected]>

fix: Apply suggestions from code review

9906971

Signed-off-by: Jana Peper <[email protected]>

fix: handling of unavailable uids

466b828

Signed-off-by: Jana Peper <[email protected]>

feat: token deletion logic

df1f1e1

Signed-off-by: Jana Peper <[email protected]>

fix: rename field names of tokenNeeded

a4c4d5a

Signed-off-by: Jana Peper <[email protected]>

fix: add default to tokenNeeded

fa6a91a

Signed-off-by: Jana Peper <[email protected]>

feat: add information about token validity times

7330786

Signed-off-by: Jana Peper <[email protected]>

fix: fix psalm

eec8e4d

Signed-off-by: Jana Peper <[email protected]>

chore: bump version nr

dfd0e8c

Signed-off-by: Jana Peper <[email protected]>

refactor: use constants for db column types

8e83208

Signed-off-by: Jana Peper <[email protected]>

fix: translate token name

3991ec0

Signed-off-by: Jana Peper <[email protected]>

fix: include review feedback

9760354

Signed-off-by: Jana Peper <[email protected]>

fix: remove redundant db column

f05eef6

Signed-off-by: Jana Peper <[email protected]>

fix: regenerate openapi.json

e9d0c05

Signed-off-by: Jana Peper <[email protected]>

janepie force-pushed the feat/webhook-tokens branch 2 times, most recently from 3669f4c to c45c268 Compare November 20, 2025 15:50

marcelklehr reviewed Nov 20, 2025

View reviewed changes

marcelklehr approved these changes Nov 20, 2025

View reviewed changes

janepie force-pushed the feat/webhook-tokens branch 2 times, most recently from 959d97d to be08ce8 Compare November 20, 2025 16:14

come-nc requested changes Nov 24, 2025

View reviewed changes

feat: error handling

a38ab95

Signed-off-by: Jana Peper <[email protected]>

janepie force-pushed the feat/webhook-tokens branch from be08ce8 to a38ab95 Compare November 24, 2025 14:10

	$data['tokens'] = $this->tokenService->getTokens($webhookListener, $data['user']['uid']);
	$data['tokens'] = $this->tokenService->getTokens($webhookListener, $data['user']['uid'] ?? null);

	$this->tokenMapper->invalidate($this->tokenMapper->getTokenById($token->getTokenId())->getToken()); // delete token itself
	$this->tokenMapper->delete($this->tokenMapper->getTokenById($token->getTokenId())); // delete token itself

	foreach ($tokenNeeded['user_roles'] as $function) {
	foreach ($tokenNeeded['user_roles'] as $user_role) {

Uh oh!

Feat(webhook_listeners): add auth tokens to webhook call #55790

Are you sure you want to change the base?

Feat(webhook_listeners): add auth tokens to webhook call #55790

Conversation

janepie commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Checklist

Uh oh!

julien-nc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oleksandr-nc commented Oct 27, 2025

Uh oh!

julien-nc commented Oct 27, 2025

Uh oh!

oleksandr-nc commented Oct 27, 2025

Uh oh!

julien-nc commented Oct 27, 2025

Uh oh!

janepie commented Nov 20, 2025

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

janepie commented Oct 15, 2025 •

edited

Loading