Image API Webhooks: Reliable Asynchronous Processing
Image processing jobs do not always finish within the comfortable lifetime of an HTTP request. A small resize may return quickly, while upscaling, restoration, background removal, or a burst of queued work can take longer. If the client keeps a connection open until every image is ready, variable processing time becomes an application problem: requests time out, workers remain occupied, and a completed result can be lost when the connection closes.
An asynchronous image processing API separates job submission from result delivery. The client submits work, stores the returned job identifier, and continues serving other traffic. The processing service completes the job in the background. A webhook then tells the client where to find the result. This model is useful for batch imports, marketplace listings, media libraries, and any workflow in which processing time is less predictable than an ordinary request-response cycle.
What changes when image processing becomes asynchronous
A synchronous endpoint combines two responsibilities: accepting a request and returning the finished asset. An asynchronous endpoint splits them. The first exchange confirms that the service received the job. Completion arrives later through a callback or a separate status lookup.
The exact HTTP response depends on the provider's contract. Some APIs use 202 Accepted, while others return a successful response containing a job ID. The important part is not a specific status code. It is the durable correlation between the submitted request, the provider's job identifier, and the final callback.
The lifecycle of an asynchronous image job
A production integration usually follows six stages:
- Submit the job. The application sends an image reference or upload, processing options, and a callback destination supported by the provider.
- Persist the correlation. The application stores its own request ID alongside the provider's job ID before treating submission as complete.
- Process in the background. The image service runs the requested operations without requiring the original connection to remain open.
- Receive the callback. The provider sends the completion payload to the configured webhook endpoint.
- Acknowledge and enqueue. The receiver validates the request, records the delivery, places follow-up work on a durable queue, and returns a successful response promptly.
- Finalize the asset. A worker downloads or references the result, updates the local job state, and triggers the next step in the application.
This division keeps the public webhook route small. Database transformations, asset downloads, notifications, and further image operations belong behind the queue, not inside the callback request.
Using webhooks with the Deep-Image.ai API
Deep-Image.ai supports a completion webhook specified in the processing request. In the current API documentation, the request contains a webhooks object with a complete property set to the receiver URL. The service sends job information to that address when processing finishes. The documented callback contains the job identifier, the original request data, and result fields such as result_url.
This detail matters because parameter names are part of the API contract. A generic field such as callback_url should not be substituted for the documented webhooks.complete structure. Deep-Image.ai also documents an account-level webhook option that can be configured with its staff when a request-specific destination cannot be supplied.
The official Deep-Image.ai webhook documentation should remain the source of truth for the current request and callback shape. If a callback does not arrive, keep the original job ID and use the documented result-status flow instead of submitting the same image again. This avoids creating duplicate work while preserving a recovery path.
Design the receiver for duplicate delivery
Webhook delivery should be treated as at least once from the receiver's point of view. Even when a provider does not document retries, network failures can make the sender and receiver disagree about whether an event was accepted. A proxy may forward a request while dropping the response, or an operator may replay a delivery during incident recovery.
Make the handler idempotent by choosing a stable deduplication key. The provider's job ID is a natural starting point for a completion event. Insert the delivery record with a uniqueness constraint, or perform a conditional state transition such as processing to complete. If the same callback arrives again, return success without creating a second asset record, notification, or downstream job.
Do not use the result URL alone as the key. URLs can change, expire, or represent more than one output. Keep the provider job ID, your internal request ID, the received timestamp, and the resulting asset references as separate fields.
Acknowledge quickly, process later
The webhook endpoint should do only the work required to accept the event safely. Parse the request, perform the checks supported by the provider, write the event to durable storage or a queue, and return a 2xx response. Downloading a large image or running another enhancement before replying increases the chance that the sender considers the delivery unsuccessful.
A durable queue also gives the application controlled concurrency. Workers can limit simultaneous downloads, apply backpressure, and retry internal failures without asking the image API to repeat the original processing job. For larger workloads, this pattern complements the controls described in our guide to scaling high-volume image pipelines.
Secure the callback endpoint
A webhook is a public HTTP endpoint, so receiving a syntactically valid payload is not enough. Use HTTPS, restrict accepted methods and content types, limit request size, and keep credentials out of the callback URL. If the provider supplies a signing secret or signature header, verify the signature against the raw request body before parsing or mutating data. Follow that provider's documented algorithm and header names rather than copying another service's convention.
Authorization should be paired with replay protection. Where the provider exposes a delivery ID or signed timestamp, store or validate it within an appropriate time window. If those fields are not part of the contract, idempotent handling of the job ID remains essential. Avoid inventing an IP allowlist unless the provider publishes and maintains its delivery ranges.
Log enough context to investigate failures, but do not log API keys, signed URLs, full authorization headers, or sensitive source data. Operational logs normally need the internal request ID, provider job ID, event state, response status, attempt count, and timing information.
Track a small, explicit job state machine
A local state model makes callback handling easier to reason about. A submitted job can move through states such as queued, processing, complete, and failed. Record transitions rather than inferring state from the presence of a result URL. This helps distinguish a job that is still running from one whose callback was received but whose result download failed.
Transitions should be monotonic unless a documented retry creates a new attempt. For example, a late duplicate callback must not move a completed job back to processing. If events can arrive out of order, compare their provider timestamps or accept only transitions allowed by the state machine.
For multi-step systems, keep the image job separate from downstream automation. A completed enhancement may trigger optimization, publishing, moderation, or human review. Those are new jobs with their own state and retry policy. The separation is especially useful in agentic image workflows with approval gates.
Plan for callbacks that never arrive
Webhooks reduce polling, but they do not eliminate the need for reconciliation. Store a deadline or next-check time for every submitted job. A scheduled worker can inspect records that remain incomplete beyond the expected window and query the provider's status endpoint using the existing job ID.
Reconciliation should be conservative. Do not resubmit an image merely because a callback is late. First check the job status. If the provider reports completion, finalize the existing job. If it reports processing, extend the check window. Resubmission should happen only when the API contract and your product logic make it safe.
Useful operational signals include callback latency, time from callback receipt to acknowledgment, duplicate-delivery rate, queue age, failed result downloads, and jobs recovered by reconciliation. These measurements reveal whether the bottleneck is image processing, webhook delivery, or your own worker pool. They also help tune the concurrency and payload decisions covered in image API rate-limit and payload planning.
Production checklist
- Persist the provider job ID and an internal request ID.
- Use the callback field documented by the image API.
- Accept the webhook over HTTPS and apply provider-supported verification.
- Deduplicate events before triggering side effects.
- Write accepted events to durable storage or a queue.
- Return a 2xx response before downloading or transforming the result.
- Keep retries bounded and observable.
- Reconcile jobs whose callbacks are missing or delayed.
- Test duplicate, delayed, malformed, and out-of-order deliveries.
Build the callback path as a separate system
Moving image processing off the request path solves only the first timeout problem. A reliable integration also needs durable correlation, a fast receiver, duplicate protection, clear job states, and a recovery path for missing callbacks. Treating the webhook as an event-ingestion boundary rather than a place to run business logic keeps those concerns visible.
Start with the documented Deep-Image.ai callback shape, store every job ID, and make completion safe to process more than once. From there, queues and reconciliation let the same design scale from a single upload to a high-volume pipeline without keeping users or application workers waiting on the image model.
