[Task] v1 publishing async ops: polling status endpoint + optional webhook callback
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 970
- Forks
- 486
- Avg merge
- 3d 33m
- Merged PRs (30d)
- 170
Description
Context
Surfaced by the Publishing Queue migration spike (#36039).
Several backend operations return immediately and complete asynchronously, with the result delivered only via a browser-side WebSocket system message:
DELETE /v1/publishing/purge(PublishingResource:894)DELETE /bundle/ids(BundleResource:369)DELETE /bundle/olderthan/{olderThan}(BundleResource:550)DELETE /bundle/all,/all/fail,/all/success(BundleResource:604+)POST /bundle(async upload,BundleResource:951)POST /bundle/_generate(BundleResource:795)
Non-browser API clients (the dotCMS SDK, integration scripts, CI pipelines) cannot observe completion. They have to either poll the list endpoint with heuristics or just fire-and-forget.
The new Angular store will handle the browser case fine via the existing WebSocket plumbing, but the platform should offer a polling / callback alternative for non-browser clients.
Proposed change
Two complementary additions:
1. Operation tracking
Each async op returns an operation id in its 202 Accepted response body:
{
"operationId": "01KT...",
"kind": "purge|delete-bundles|delete-older-than|generate|upload-async",
"submittedAt": "...",
"message": "..."
}
Add a status endpoint:
GET /v1/publishing/operations/{operationId}
→ { operationId, kind, state: "pending|running|completed|failed", startedAt?, finishedAt?, message? }
State is read from a simple in-memory or persisted operation registry; entries TTL out after 24h.
2. Optional webhook
Accept an optional ?callbackUrl=... parameter on the async endpoints. On completion, POST the status payload to the URL with HMAC signing for verification. Behind a config flag.
Acceptance criteria
- Async endpoints return an
operationId GET /v1/publishing/operations/{operationId}returns the current state of any in-flight or recently-completed operation- Webhook delivery has a single retry on 5xx and signs the body with an HMAC header
- OpenAPI updated
- Integration tests for the polling endpoint and the webhook path
Source links
- Spike audit: #36039
- Epic: #34734
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the async operations listed in PublishingResource:894 and BundleResource:369, 550, 604+, 795, and 951, then read spike #36039 to understand the existing completion flow. Done means the specified operations expose status tracking and optional signed callbacks, with OpenAPI coverage and integration tests for polling and webhooks.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100