Developer guide
Webhook Patterns for Reliable Image Generation
A webhook makes image generation event-driven: a post publishes, a product changes price, a listing becomes active, or a customer reaches a milestone. The rendering call is only one part of the integration; reliability depends on everything around it.
· 9 minute read
Verify before processing
Validate the sender using its documented signature, timestamp, or shared-secret mechanism. Reject stale or invalid requests before storing payload data or initiating a generation.
- ✓Read the raw body when signature rules require it
- ✓Compare signatures using a timing-safe method
- ✓Reject timestamps outside the allowed window
- ✓Keep secrets outside source control
Acknowledge quickly and process asynchronously
Many webhook senders retry if a response takes too long. Store the event, return a success response, and let a queue or workflow worker perform validation and image generation. This separates sender reliability from render time.
Make every event idempotent
Webhook delivery is commonly at least once, so duplicates are normal. Store the provider event ID or construct a key from the source record and meaningful version.
If the key already completed, return the previous output. If it is in progress, avoid starting a second job. If it failed permanently, require a deliberate retry after the source data is fixed.
Separate temporary and permanent failures
Retry timeouts and temporary service failures with backoff. Do not repeatedly retry missing required fields, invalid template IDs, or inaccessible source images. Surface those errors to the record owner.
Frequently asked questions
Should a webhook return the final image URL?
Only when the sender supports a long enough synchronous response. Otherwise return an acknowledgement and deliver the result through storage, polling, or a callback.
How many times should generation be retried?
Use a small bounded retry policy for temporary failures, then move the event to a visible review or dead-letter queue.