Use a provider callback to turn image generation into an event-driven workflow: start the job, expose a public HTTPS endpoint, verify the provider’s signature against the untouched request body, acknowledge with a 2xx response after durable enqueueing, and let a worker retrieve and process the image. This pattern avoids constant polling while keeping downloads and transformations out of the webhook request.
What an image-generation webhook does
A webhook is an HTTP request initiated by an image API when something happens to a job. Your application supplies a URL; the provider sends a POST containing an event, status, or identifier. Your receiver validates it, records the event, and queues follow-up work.
The callback is a notification, not necessarily the image itself. Use the provider’s documented result endpoint and the stored provider job ID to retrieve the output. Image URLs, access controls, and retention periods differ, so download or copy results into storage that you control when your workflow requires long-term access.
Implementation sequence
1. Select the provider event
Decide whether you need every intermediate output, only terminal success, or failures and cancellations too.
Recommended Free Tools
#1 Best Overall
- OpenAI: configure one or more subscriptions at project level. A background response can emit
response.completed; the receiver can then retrieve the response by its ID. See the OpenAI Webhooks guide and endpoint reference. - Replicate: pass a webhook URL when creating a prediction. Filters include
start,output,logs, andcompleted. Output and log notifications are throttled to at most once every 500ms, while requested start and completed events are sent regardless of that throttling. Read Replicate’s setup guide. - Stability AI: its reviewed API reference documents image-generation endpoints and API-key authentication, but does not establish an equivalent native webhook workflow. Confirm current capability before designing around callbacks; polling or an orchestration service may be necessary. See the API reference.
2. Create a public HTTPS receiver
Deploy a route such as POST /webhooks/image-generation with a certificate and a stable hostname. OpenAI’s endpoint creation requires HTTPS. For local experiments, its guide names ngrok and cloud development environments as ways to obtain public reachability. Configure the production URL directly: OpenAI does not follow redirects, and a 3xx response is a failed delivery.
3. Map provider jobs to your requests
When you start generation, persist the provider’s prediction or response ID beside your internal request ID, destination, and processing state. Match callbacks to that stored record. Do not let arbitrary client-supplied routing fields decide where an image is published.
4. Verify the signature before doing anything else
Read and retain the raw bytes or raw text. Do not parse and re-serialize JSON before verification because whitespace and escaping changes can invalidate a signature.
OpenAI verification
OpenAI provides SDK webhook helpers and recommends signature verification, especially when events trigger backend actions. In Express, retain the raw text body for the helper, then reject an invalid signature before queueing work. Keep the signing secret in server-side secret storage and rotate it if exposed.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
- Used Book in Good Condition
Replicate verification
Replicate sends webhook-id, webhook-timestamp, and webhook-signature. Its signed content combines the ID, timestamp, and raw body. Verify HMAC-SHA256 with the base64 key portion of the signing key, compare signatures in constant time, and enforce a timestamp tolerance to reduce replay risk. Follow the current verification documentation for the exact encoding and key format.
5. Acknowledge quickly and enqueue
After validation and durable enqueueing, return a successful 2xx immediately. Do not download images, resize them, call another API, or publish content in the request handler. OpenAI documents retries for unsuccessful or slow deliveries for up to 72 hours with exponential backoff. Duplicate deliveries can occur; use the provider event ID as an idempotency key and record it before irreversible side effects.
6. Process in a worker
A worker consumes the queue, loads the saved provider ID, retrieves the result through the provider’s documented API, and stores or transforms the image. Handle success, failure, and cancellation as separate terminal states. Treat a callback as a state signal rather than proof that a durable image URL is present.
7. Test both paths
Exercise valid and invalid signatures, duplicate IDs, stale timestamps, malformed payloads, failed and canceled jobs, queue outages, delayed workers, and provider retries. OpenAI exposes webhook test events in dashboard settings. Use a public development endpoint, but point production configuration at the final HTTPS URL.
Minimal receiver design
The following framework-neutral flow is the essential contract:
- Accept only POST on the intended route and enforce a body-size limit.
- Capture the untouched body and provider headers.
- Reject unknown event types or malformed payloads.
- Verify the provider signature and timestamp.
- Insert the event ID into an idempotency table with a uniqueness constraint.
- Persist the event and enqueue a job in one reliable transaction or equivalent durable sequence.
- Return 2xx; let the worker perform retrieval and image processing.
Use a dead-letter queue or alerting path for events that repeatedly fail processing. Monitor signature failures, queue depth, worker errors, and delivery retries without logging secrets or complete sensitive payloads.
Provider differences that affect architecture
| Concern | OpenAI | Replicate | Stability AI |
|---|---|---|---|
| Configuration | Project endpoint with event subscriptions | Webhook URL in each prediction request | Webhook workflow not established in the reviewed reference |
| Events | Includes response.completed for background responses |
start, output, logs, completed |
Verify current product documentation |
| Verification | SDK helpers and signing secret | Signed headers, HMAC-SHA256, timestamp tolerance | Not stated |
| Delivery behavior | Retries up to 72 hours with exponential backoff; duplicates possible; redirects fail | Output/log events at most every 500ms; start/completed are not subject to that throttle | Not stated |
| Result retrieval | Retrieve by response ID after completion | Use prediction output/state APIs | Provider-specific |
Security and reliability checklist
- Use HTTPS and a dedicated route; reject unexpected methods.
- Keep API tokens and signing keys out of browser code, logs, and repositories.
- Verify the exact raw body before JSON parsing or side effects.
- Apply timestamp tolerance where supported and constant-time comparison.
- Deduplicate on provider event ID before billing, publication, or other irreversible actions.
- Return 2xx only after the event is safely recorded or queued.
- Handle failures and cancellations, not just successful images.
- Store outputs according to current provider retention rules and your access requirements.
Performance, cost, and operational notes
Webhook delivery removes polling traffic but does not remove generation, storage, or worker costs. Keep the receiver stateless so it can scale horizontally; put durable state in a database and work in a queue. Back-pressure intermediate Replicate output and log events if you do not need every update. Set worker timeouts and retries separately from webhook acknowledgement, and make image downloads resumable where supported.
Or skip the browser setup:
ScreenshotNeo is a website screenshot API and MCP server if your completed image workflow also needs automated captures of web pages. It removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and each response identifies the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
One GET request returns PNG, JPEG, WebP, or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for options such as full-page lazy-image loading, CSS selectors, device presets, custom JavaScript, waits, headers, cookies, signed links, asynchronous jobs, webhooks, and bulk capture. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting
The provider reports delivery failures
Check that DNS resolves publicly, the certificate is valid, the route accepts POST, and the response is a direct 2xx. Remove redirecting proxies and inspect access logs for authentication middleware that blocks the provider.
Signature verification always fails
Ensure the framework exposes the raw body, use the correct secret and headers, and verify the provider’s current algorithm and encoding. Check clock skew when timestamps are signed. Never verify a parsed JSON object.
The same image is processed twice
Add a unique database constraint on the provider event ID and make the worker operation idempotent. Acknowledge duplicates after recognizing the stored ID.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Images disappear later
Do not assume callback URLs are permanent. Fetch the result in the worker and copy it to durable storage according to the provider’s retention documentation.
Best Value
The webhook times out
Move all downloads and transformations behind the queue. The handler should validate, persist, enqueue, and respond; increase worker capacity rather than the provider-facing timeout.
FAQ
Can a webhook receiver be private?
Not for direct provider delivery. It needs public HTTPS reachability, although access can still be restricted with signature verification, network controls, and a dedicated route.
Should I use webhooks or polling?
Use native webhooks when the provider offers reliable event delivery and you can expose a receiver. Polling remains a fallback when callbacks are unavailable, as may be the case for some Stability AI workflows.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsIs a successful callback proof that generation succeeded?
No. Validate the event type and status, then retrieve the result using the provider ID and handle retrieval errors independently.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
