Skip to main content
Self-hosting images means copying article media into your own storage and updating the URLs your CMS renders. A webhook receiver can use the supplied images list for body images and handle featured_image_url separately. Plan for missing fields, repeated deliveries and failed downloads before replacing working media URLs. Do not assume every image comes from one CDN hostname. Validate each source URL against your receiver’s media policy. The field reference explains which fields arrive with manual publishing, scheduled publishing and Sync.

How it works

Manual and scheduled article publishing include an images array containing {url, alt} objects extracted from the prepared body. It lists quoted src values in document order and collapses repeated exact URL strings. It does not extract lazy-loading data-src values. An absent alt attribute becomes an empty alt string. Treat the array as input to a receiver workflow, not as a downloader or HTML rewrite already implemented for you:
  1. Validate the event and article identity before handling media.
  2. Validate each source URL, download an allowed image, and store it using your media adapter.
  3. Record a mapping from the original source URL to the successfully stored URL.
  4. Parse the article HTML and rewrite the appropriate image attributes using that mapping.
  5. Handle the featured-image field separately, then persist the body and media association against the same article.
  6. Check the rendered page and decide how failed or pending media jobs affect the acknowledgement.
Use exact source strings for matching the supplied list. If your HTML parser decodes entities or normalizes attribute values, make the mapping comparison consistent with that parser. Do not replace every occurrence of an image URL throughout the article: the same string could appear in a link, example or unrelated attribute.

Python receiver

Keep the Python receiver’s downloader, storage adapter and HTML rewrite separate. Download only through the validated media-fetch path described below. Add a mapping entry after the upload succeeds, then use an HTML-aware rewrite to change actual image attributes. Leave unrelated text and links intact. These illustrative inputs need the same rewrite even though their attribute formatting differs:
A replacement that searches only for src="original.jpg" misses the second form. Test your parser and serializer with single and double quotes, spaces around =, duplicate images, escaped attribute values and markup your CMS permits. Updating src also does not automatically update a site’s responsive srcset or custom lazy-loading attributes; define those transformations when your site uses them. Store the original-to-hosted mapping so a repeated delivery can reuse an existing upload rather than create another media file. Choose a deliberate policy for changed images at the same URL. A filename alone is not a reliable article or media identity. The idempotency guide covers repeated deliveries without suppressing later edits.

Security: allowlist your fetch host

A server-side image downloader needs more than a hostname check. Define approved media origins for your integration and reject URLs outside that policy. Apply the same checks to body images and the featured image. Your download policy should cover:
  • HTTPS, the allowed host and port, and resolved addresses that cannot reach private or internal services.
  • Redirect handling: disable redirects or validate every destination before following one.
  • Request and download time limits, a streaming byte limit, and an accepted HTTP result before storing the response.
  • Accepted image formats and content validation instead of trusting a filename or response header alone.
  • Bounded concurrency and storage access appropriate to the receiver.
Avoid logging credentials or signed URL query values. Review the fetcher’s actual DNS, connection and redirect behaviour rather than treating a parsed hostname as proof that the network request is safe. The controls above are receiver responsibilities; receiving a theStacc webhook does not implement them for you.

Notes

The featured image is a separate top-level field. Body preparation removes the first inline image matching that featured-image URL, allowing a query string or fragment. It leaves the content unchanged when no matching image exists or no featured-image URL is supplied. A later copy can therefore remain in the body and appear in images; do not assume the featured image is always absent from the list. Repeated exact body URLs appear once in images, so apply the stored mapping to every intended occurrence in the HTML. Different URL strings are not automatically the same media asset, even if they differ only in a query parameter. An empty alt value does not establish that an image is decorative. Review which images need a useful description and preserve appropriate alt text during rewriting. Re-hosting bytes alone does not settle accessibility, captioning or media rights. Your receiver can keep using the original URLs if that matches its media policy. If mirroring fails, do not replace a working URL with an unavailable storage destination. Either retain it, fail the operation with a useful error, or persist a durable media job under your documented policy. Use the response contract to separate acknowledgement from completed work.

Migrating blogs already published with theStacc’s URLs

Start with a test article and an existing blog_id mapping. Back up the stored body and featured-image association, mirror permitted media, rewrite the intended attributes, and update the same CMS record. Verify the public page before retiring its original media URLs. Sync sends updated body HTML and featured-image fields, but the Sync payload described in the field reference does not include images. A receiver migrating through Sync needs to discover body images itself, or use an image-bearing publish path appropriate to the article’s state. Confirm the fields for that path before starting a larger migration. Keep migration progress and failed downloads separately from article identity. Repeating the work should update the intended article, not create a fresh post because its URLs changed. Finish by checking the hero, repeated body images, alt text and any responsive-image attributes your site renders.