Designing a resilient webhook receiver for DICOMweb STOW-RS
- STOW-RS sends binary DICOM instances as multipart/related HTTP POST bodies, unlike small JSON webhooks.
- A resilient receiver streams incoming bytes directly to object storage instead of buffering requests in memory.
- Hospital scanners enforce strict socket timeouts, so handlers must respond quickly without parsing tags first.
- Respecting stream backpressure keeps memory usage flat regardless of file size during uploads.
- Background workers should handle tag extraction and decompression after the raw bytes are safely stored.
A resilient STOW-RS receiver accepts binary multipart HTTP POST requests. It streams each DICOM instance directly to cloud object storage. Unlike JSON webhooks, STOW-RS transfers multi-megabyte binary files.
These files quickly exhaust server RAM if buffered in memory. Stream incoming bytes directly from the socket to cloud storage. Then return a fast acknowledgment before the sender times out.
Understanding these streaming requirements helps you build an ingestion service. It will handle heavy hospital traffic without crashes or lost studies.
What makes a webhook receiver for STOW-RS DICOMweb unique?
Most webhooks in software engineering deliver small JSON payloads. Services like Stripe or GitHub post a few kilobytes of text to notify your application of an event. Web frameworks parse these requests by reading the entire body into memory before running your handler.
DICOMweb STOW-RS (Store Over the Web, RESTful Services) works differently. It sends actual medical imaging files inside an HTTP POST request. As defined in RFC 2387, STOW-RS packages transfers using the multipart/related media type:
POST /studies HTTP/1.1
Host: api.yourcompany.com
Content-Type: multipart/related; type="application/dicom"; boundary="boundary-xyz"
Transfer-Encoding: chunked
--boundary-xyz
Content-Type: application/dicom
<binary DICOM instance bytes>
--boundary-xyz--
Each part of the multipart body contains a complete binary DICOM file. A single digital radiography image can measure 30 MB. A high-resolution CT exam often contains 1,500 slices that exceed 800 MB across multiple requests.
If your web server tries to parse this body into memory, your application heap will collapse. Five concurrent uploads from hospital scanners will consume gigabytes of RAM in seconds. The Linux kernel will terminate your process with an Out of Memory error. A resilient receiver never buffers complete request bodies in RAM.
Why you should never buffer multipart/related bodies in memory
Standard web frameworks encourage developers to install body-parsing middleware globally. In Node.js, libraries like body-parser read the whole socket into a single buffer or string. Python frameworks like Django often buffer form uploads on disk or in memory before invoking your view.
This design fails under production medical imaging workloads for three reasons:
- Unbounded memory spikes: Memory usage scales with file size multiplied by active uploads. A spike in hospital transfer activity can exhaust all server RAM.
- Garbage collection stalls: Allocating and freeing 100 MB buffers forces the garbage collector to pause. These pauses freeze other active connections on the same worker.
- Premature connection drops: Loading a large transfer into memory delays your response. If memory pressure slows processing, the client socket times out before your application sends a single header.
To handle production traffic, your receiver must treat the HTTP request as an unbuffered byte stream. To see how streaming simplifies data compliance, read our guide on stateless streaming pipelines for healthcare privacy.
How to stream binary multipart parts directly to object storage
To avoid memory exhaustion, parse multipart boundary delimiters directly from the incoming stream. As each part begins, pipe its binary bytes straight to cloud object storage like Amazon S3 or Google Cloud Storage.
Incoming HTTP Socket
|
v
[Streaming Multipart Parser] (RFC 2046 boundary search)
|
+---> Part 1 Stream ---> S3 / GCS Multipart Upload
|
+---> Part 2 Stream ---> S3 / GCS Multipart Upload
|
v
[Fast HTTP 200/202 Response]
RFC 2046 governs how multipart boundaries separate each file. A streaming parser scans incoming byte chunks for the boundary delimiter without storing the whole payload. When it finds a part header with Content-Type: application/dicom, it exposes that part as a readable stream.
You can pipe that readable stream directly into an object storage client.
import http from "node:http";
import { Upload } from "@aws-sdk/lib-storage";
import { S3Client } from "@aws-sdk/client-s3";
import Busboy from "busboy";
const s3 = new S3Client({ region: "eu-central-1" });
export function createReceiver() {
return http.createServer((req, res) => {
if (req.method !== "POST" || !req.url?.startsWith("/studies")) {
res.writeHead(404).end();
return;
}
const contentType = req.headers["content-type"] || "";
if (!contentType.includes("multipart/related")) {
res.writeHead(415, { "Content-Type": "text/plain" }).end("Unsupported Media Type");
return;
}
const busboy = Busboy({ headers: req.headers });
const uploadPromises: Promise<unknown>[] = [];
busboy.on("file", (name, fileStream) => {
const storageKey = `incoming/${Date.now()}-${Math.random().toString(36).slice(2)}.dcm`;
const upload = new Upload({
client: s3,
params: {
Bucket: "clinical-ingest-bucket",
Key: storageKey,
Body: fileStream,
ContentType: "application/dicom",
},
});
uploadPromises.push(upload.done());
});
busboy.on("finish", async () => {
try {
await Promise.all(uploadPromises);
res.writeHead(200, { "Content-Type": "text/plain" }).end("Instances stored");
} catch (err) {
res.writeHead(500).end("Storage write failed");
}
});
req.pipe(busboy);
});
}
We recommend piping incoming streams straight to object storage instead of writing temporary files to local container disks. Local container disks fill up quickly, degrade I/O performance, and make horizontal scaling difficult.
Direct streaming has one limitation. You cannot read DICOM tags or validate study identifiers before storing the object. You must store the raw binary bytes first.
Once the file lands safely in object storage, trigger a background worker to parse tags and index metadata. To understand how DICOM files structure tags, read our guide on how imaging data splits into instances and studies.
How should your receiver respond to avoid sender timeouts?
Hospital scanners enforce strict socket timeouts. Most disconnect if your server does not respond within 30 to 60 seconds.
Never decompress pixel data, run AI inference, or query external services inside the HTTP handler. These slow tasks cause client timeouts. Your receiver only needs to authenticate the request, stream the binary parts to durable storage, and send the HTTP response.
Choosing the right HTTP status code
RFC 9110 and the DICOMweb specification define standard status codes for STOW-RS:
| Status Code | When to use it | Sender reaction |
|---|---|---|
200 OK |
All instances stored successfully | The sender marks the transfer complete. |
202 Accepted |
The payload was accepted for processing | The sender marks the transfer complete. |
400 Bad Request |
Malformed headers or missing multipart boundary | The sender fails and alerts an administrator. |
415 Unsupported Media Type |
Content-Type is not multipart/related |
The sender will not retry. |
500 Internal Server Error |
Object storage failed or timed out | The sender logs an error and retries later. |
503 Service Unavailable |
The receiver is overloaded | The sender backs off and retries. |
You can review how Dicomly formats STOW-RS deliveries and headers to identify sending devices without parsing the binary body.
Handling backpressure and chunked transfer encoding
Network connections between hospitals and cloud environments often experience variable throughput. Your receiver must manage data flow cleanly at the TCP layer.
Applying stream backpressure
Backpressure prevents your server from reading data from the network faster than your storage destination can write it. If a scanner uploads faster than your storage API can write, unwritten bytes pile up in server memory.
When using Node.js streams or Go channels, always pipe data using primitives that respect backpressure. A standard .pipe() call automatically pauses the incoming network socket when the destination write buffer fills up. When storage drains the buffer, the runtime resumes reading from the network socket. This keeps memory usage flat regardless of file size.
Supporting chunked transfer encoding
RFC 9112 defines chunked transfer encoding for HTTP/1.1. Many clinical push systems do not include a Content-Length header on large STOW-RS POST requests. Because the sender streams instances as the scanner acquires them, the total byte count is unknown when the request starts.
Ensure your reverse proxy and HTTP framework support Transfer-Encoding: chunked. Never configure a proxy to require a Content-Length header on your STOW-RS routes. Doing so will cause the proxy to reject valid clinical transmissions with an HTTP 411 Length Required error.
To compare classic store commands with web transfers, read our guide on C-STORE vs DICOMweb STOW-RS.
Handling partial transfers and aborted connections
Network connections drop. A hospital router might reboot. A firewall state table can expire. A technician may cancel an exam at the scanner.
When a client closes the TCP connection before sending the final multipart boundary, your receiver must clean up incomplete resources:
- Abort pending storage uploads: Cloud object storage multipart uploads charge for uncompleted parts if you do not abort them. Catch socket
closeevents and cancel in-flight multipart uploads immediately. - Handle orphan instances: A sender might disconnect after three instances of a ten-slice series. Decide how your downstream worker handles incomplete studies. Do not trigger processing workflows immediately upon receiving the first instance.
- Idempotent keys: Clinical systems frequently retry failed transmissions. Use deterministic storage keys or check SOP Instance UIDs to ensure retried files overwrite partial uploads rather than creating duplicates.
To understand why modalities retry failed transfers, read our guide on push vs pull in medical imaging workflows.
Five rules for production STOW-RS receiver reliability
Follow these five engineering rules when putting a STOW-RS receiver into production:
- Turn off global body parsers: Keep your STOW-RS route as an unbuffered byte stream.
- Stream directly to object storage: Never buffer multi-megabyte payloads in application RAM or ephemeral container disks.
- Respect backpressure: Ensure your pipeline pauses network reads when storage writes slow down.
- Respond within seconds: Persist the raw bytes and return HTTP 200 or 202 before running any clinical parsing.
- Decouple processing with background queues: Let background workers handle tag extraction, decompression, and metadata indexing.
To test these patterns with a working endpoint, follow our quickstart guide for receiving your first delivery.
Dicomly builds infrastructure for healthcare software teams that receive DICOM studies from hospitals. Why we built Dicomly →