
Add a completion callback by running your own polling worker and delivery service. Imagild's current media API does not accept a webhook callback field. Your worker reads the saved task, records a confirmed outcome, and delivers an application-owned event to a configured receiver.
Key Takeaways
- Poll Imagild; send callbacks from your own service.
- Persist one event ID and payload before delivery so retries remain identifiable.
- Sign your callback with a separate secret, and make the receiver deduplicate events.
Keep the provider contract separate
Submit the generation through the Imagild API console's documented endpoints, preserving the operation key and returned task ID. Do not insert webhook, callback_url, or custom event fields into the strict generation JSON.
Your service can periodically read GET /tasks/{id}, respecting poll_after_seconds and account limits. When the task succeeds or fails, create the appropriate event in your own database. An unknown outcome should enter reconciliation rather than a fabricated success event.
This pattern adds application integration behavior. It does not create an Imagild webhook guarantee, callback SLA, or streaming endpoint.
Use an outbox instead of sending before saving
A durable delivery record can contain:
| Field | Purpose |
|---|---|
| Event ID | Stable deduplication identity |
| Owned task ID and observed outcome | Links event to actual work |
| Serialized event payload | Preserves the exact event content |
| Configured destination reference | Selects an authorized receiver |
| Delivery attempt and next-attempt time | Supports bounded retries |
| Acknowledgment state | Distinguishes observed outcome from delivered notification |
Save the event and its relationship to the observed task before attempting HTTP delivery. If the process crashes after sending but before recording acknowledgment, the receiver may see the event again. Treat delivery as retryable, with duplicate handling, rather than promising exactly-once notifications.
Use preconfigured HTTPS destinations and validate their ownership. Do not turn a user-supplied arbitrary URL into an unrestricted server-side request target.
Sign the bytes you actually send
This native Node.js example defines an illustrative application callback signature. It is not an Imagild header protocol.
import { createHmac } from "node:crypto";
function callbackHeaders(rawBody, unixSeconds, callbackSecret) {
const timestamp = String(unixSeconds);
const signed = timestamp + "." + rawBody;
const signature = createHmac("sha256", callbackSecret)
.update(signed, "utf8").digest("hex");
return {
"Content-Type": "application/json",
"X-App-Callback-Time": timestamp,
"X-App-Callback-Signature": signature
};
}
Node's crypto documentation specifies HMAC construction. Generate the serialized event body once and sign those exact bytes. Do not parse and reserialize them between signing and delivery.
Use a callback-specific secret from your secret store. Never put the Imagild API key in the payload or use it as the receiver's notification credential.
Verify and deduplicate at the receiver
The receiver should validate the signature over the raw body, enforce its chosen timestamp freshness policy, and compare signatures safely. Then authorize the event's tenant relationship and insert its event ID into a deduplication record before applying the business effect.
A duplicate valid event should return the appropriate acknowledgment without delivering a second email, publishing the asset twice, or charging again. A signed event still needs schema validation; a signature is not permission to perform arbitrary actions.
OWASP's REST guidance supports endpoint authentication, authorization, and controlled input handling. Your implementation must define retry limits, secret rotation, and failure review.
Test the notification failure separately from generation
Use fixtures to simulate duplicate delivery, wrong signatures, stale timestamps, receiver downtime, and a crash after acknowledgment. These are proposed acceptance tests, not completed provider webhook tests.
If delivery fails after generation succeeds, retry the event rather than generating another image. Current models and generation points remain in the model market; API access requires active membership.
Use the failed-job guide for actual generation uncertainty and the asset archive guide for verified stored outputs. Keep task outcome, media delivery, and callback acknowledgment as separate recoverable stages.
Related tasks
- What Should You Check Before Retrying a Failed Image or Video Job?
- How to Archive Imagild Assets Before the 90-Day Storage Window Ends
Sources and scope
- Imagild API console: Async polling contract with no current webhook field.
- Imagild model market: Generation cost distinct from application callback retry.
- Node.js createHmac: HMAC SHA256 construction over sender-defined exact bytes.
- OWASP REST Security Cheat Sheet: Receiver endpoint authentication, authorization and schema/input controls.
Product instructions were checked against the current Imagild API contract and the public model catalog. Code, budgets and acceptance checks are illustrative; this article does not claim a new paid generation test, an uptime measurement, a search-volume study or a ranking of AI citations.
Prepared by Imagild Editorial, the company editorial team responsible for these guides. AI assisted research and drafting. This is documentation-based guidance with proposed examples, not a claim of hands-on testing or an independent product review. Report a correction.
Cover: Original Imagild product screenshot captured on 28 October 2026; model availability and prices may change. This image is not an API response or a performance benchmark.