[vitormattos]

Goal

Expose the remaining useful LibreSign business transitions to Nextcloud Webhook Listeners, without creating a proprietary callback transport. The existing SigningRequestCompletedEvent remains unchanged.

Native events added (LibreSign development main / Nextcloud 36)

PHP event class (OCA\Libresign\Events)	Business trigger	Payload scope
SigningRequestReadyEvent	Root document draft → ready-to-sign, including newly created ready requests	request UUID/type, status, versioned event ID
SigningRequestCanceledEvent	Root document or envelope enters canceled state through a committed rejection	root request UUID/type, status, event ID
SignerRejectedWebhookEvent	One committed business rejection, independent of number of identification methods	root UUID, document UUID, non-secret signer ID, cancellation flag
SignerSignedWebhookEvent	One persisted signer/document signing result (multiple child results possible for envelopes)	root UUID, document UUID, non-secret signer ID, signed status
NotificationDeliveryStatusChangedEvent	One persisted channel submission outcome after the delivery ledger commits	root UUID, delivery ID, channel, state, attempt; accepted ≠ recipient received

All payloads have contractVersion: 1 and a deterministic eventId for downstream deduplication; no email, phone number, signing link, private rejection comment, PDF bytes or certificate is serialized. Typed PHP events remain independent of Nextcloud HTTP transport.

Important semantics

• Individual signature events represent document-level signer actions; signing an envelope can generate more than one document-level event.
• A rejection under a continue policy may complete a previously partially signed workflow; it now also emits the existing aggregate completion event.
• The old internal SignRequestCanceledEvent is signer-removal notification, not a workflow-canceled webhook. New SigningRequestCanceledEvent is explicitly aggregate.
• A notification outcome is persisted transport-adapter submission state, not proof of recipient delivery. The existing delivery ledger/worker is retained.
• Future integrations need authenticated subscriptions, idempotence and authorized OCS/WebDAV reconciliation. Stable LibreSign 13–15 are not changed.

Validation

• NC36 / PHP 8.5, isolated local environment: 359 focused unit tests / 904 assertions and 6 notification integration tests / 38 assertions with a real SQLite ledger.
• The notification integration test checks that listeners observe the committed accepted outcome and attempt, outside the SQL transaction, without recipient email or encrypted recipient in the serialized event.
• PHP-CS-Fixer dry-run and git diff --check: clean on the revised tests. Signed incremental commits have verified DCO.
• GitHub Actions at 2a14994: 74 successful checks, 6 intentionally skipped, 0 failures or pending checks. PHPUnit passed on SQLite, MariaDB 12.3, PostgreSQL 18 and MySQL 9.7 (PHP 8.3/8.4/8.5); Behat passed across all four database backends; Playwright E2E passed 88 browser tests. The previous November 9 failures included a GitHub Actions incident and a test fixture UUID longer than the SQL varchar(36) limit; both are resolved.
• HTTP POST homologation remains outstanding for each newly exposed event. The existing completion event was verified separately. Do not interpret unit/integration event dispatch as an end-to-end Webhook Listeners delivery guarantee; keep this as a pre-merge verification item.

Review notes

• Notification outcome publishing is separate from SMTP submission and reads the persisted ledger.
• Error handling distinguishes recoverable exceptions from programming errors, and rejection-event failures do not suppress later business events.
• Ready-to-sign events are emitted after signer persistence, with focused negative tests for failed persistence.
• No email, phone number, signing link, rejection comment, PDF bytes or certificate are intentionally serialized by these event payloads.

Related

Complements #9426 (remove legacy callback); developed as a separate, independently reviewable PR against main. Neither merge nor deploy is authorized.

[github-actions]

Code Metrics Report

	main (b02d0b8)	#9427 (d56d41c)	+/-
Coverage	76.1%	76.3%	+0.1%
Test Execution Time	1s	1s	0s

Details

  |                     | main (b02d0b8) | #9427 (d56d41c) |  +/-  |
  |---------------------|----------------|-----------------|-------|
+ | Coverage            |          76.1% |           76.3% | +0.1% |
  |   Files             |            500 |             506 |    +6 |
  |   Lines             |          28578 |           28752 |  +174 |
+ |   Covered           |          21776 |           21946 |  +170 |
  | Test Execution Time |             1s |              1s |    0s |

Code coverage of files in pull request scope (82.9% → 84.4%, patch 95.7%)

Files	Coverage	+/-	Patch Coverage	Status
apps/libresign/lib/Events/SigningRequestCompletedEvent.php	100.0%	+7.6%	-	affected
lib/Events/NotificationDeliveryStatusChangedEvent.php	100.0%	+100.0%	100.0%	added
lib/Events/SignerRejectedWebhookEvent.php	100.0%	+100.0%	100.0%	added
lib/Events/SignerSignedWebhookEvent.php	100.0%	+100.0%	100.0%	added
lib/Events/SigningRequestCanceledEvent.php	100.0%	+100.0%	100.0%	added
lib/Events/SigningRequestReadyEvent.php	100.0%	+100.0%	100.0%	added
lib/Service/FileStatusService.php	97.9%	+0.1%	100.0%	modified
lib/Service/Notification/NotificationDeliveryEventPublisher.php	100.0%	+100.0%	100.0%	added
lib/Service/Notification/NotificationSubmissionService.php	95.7%	+0.0%	100.0%	modified
lib/Service/RequestSignatureService.php	79.6%	+0.8%	95.4%	modified
lib/Service/SignFileService.php	79.8%	+0.2%	75.0%	modified
lib/Service/SignatureRejection/SignatureRejectionService.php	96.6%	-3.4%	86.0%	modified

---

Reported by octocov