Midjourney API Webhook Guide
Webhooks are the cleanest way to handle Midjourney API jobs in production. Instead of checking status repeatedly, your app submits a job, stores the task ID, and waits for a callback when the result is ready.
How the Webhook Flow Works
Submit the job with hookUrl
When you call /midjourney/v1/submit-jobs, include a public HTTPS endpoint in hookUrl. The API returns a taskId immediately, which you should store before waiting for the callback.
Persist the task ID in your app
Save the task ID together with your prompt, user ID, selected mode, and internal status. That gives your webhook handler a stable way to reconcile the callback later.
Receive the callback on completion
When the generation finishes, your webhook endpoint receives a POST payload. Use it to update the job record, save image URLs, and trigger notifications or follow-up workflows.
Keep polling as a fallback path
Even if webhooks are your main flow, keeping job-status available helps when a callback is delayed, a deployment is in progress, or you need manual reconciliation.
Submit a Job with hookUrl
curl -X POST "https://api.midjourney-api.com/midjourney/v1/submit-jobs" \
-H "Content-Type: application/json" \
-H "API-KEY: your_api_key" \
-d '{
"prompt": "editorial fashion portrait with soft natural light --ar 4:5",
"mode": "fast",
"hookUrl": "https://yourapp.com/webhooks/midjourney"
}'Why teams prefer webhooks
- •Fewer repeated status requests from your backend
- •Cleaner fit with async queues and background processing
- •Faster downstream automation once the result is ready
- •Simpler UX for notifying users when generation completes
Recommended Endpoint Logic
Your webhook handler should be small and deterministic: receive the payload, map the task ID, update the job state, persist the output, and hand off anything expensive to a worker queue.
- •Return a fast 2xx response from your webhook route and move heavy work into a queue or background job.
- •Store task IDs before the callback arrives so you can reconcile results idempotently.
- •Log failed callbacks and keep a polling fallback for operational recovery.
- •Use a dedicated endpoint such as /webhooks/midjourney instead of mixing multiple callback types together.
- •Treat webhook processing as asynchronous business logic, not as a place for long-running synchronous work.
Fields to Persist
| Field | Why It Matters |
|---|---|
| taskId | Use it to map the callback to your internal job row or queue item. |
| status | Check whether the job succeeded, failed, or is still pending in your own system. |
| image / images | Persist the final generated image URLs for later display or processing. |
| prompt / mjPrompt | Useful for debugging, analytics, and support workflows. |
| meta | Optional metadata can help with image display or downstream transformations. |
Webhooks vs Polling
| Approach | Best For | Tradeoff |
|---|---|---|
| Webhooks | Production apps, async pipelines, notifications | Requires a public callback endpoint |
| Polling | Quick prototypes, local tests, manual troubleshooting | More repeated status requests |
Frequently Asked Questions
What is hookUrl in Midjourney API?
hookUrl is the callback endpoint you pass when submitting a job. When image generation completes, the API posts the result to that URL so your backend can process it asynchronously.
Should I use webhooks or polling?
Polling is fine for simple prototypes, but webhooks are usually the better production choice because they reduce repeated status checks and fit queue-based backend workflows more naturally.
Do I still need job-status if I use webhooks?
Usually yes as a fallback. Many teams use webhooks as the primary flow and keep job-status polling as a safety net when a callback is delayed or unavailable.
What should my webhook endpoint do?
At minimum, it should validate the request, map the task ID to your internal job record, persist the image result, and trigger any downstream notifications or business logic.
Next Pages to Read
Getting Started
See the full job lifecycle from API key to first generated image.
Replicate Alternative
See when a dedicated Midjourney workflow is a better fit than a broader platform.
Features
Review webhook support alongside concurrency, Niji, and mode controls.
Node.js Tutorial
Build an async callback flow with fetch and TypeScript.
Use Webhooks to Ship Cleaner Midjourney Integrations
Start with a simple callback endpoint, then scale into queues, notifications, and downstream automation once results arrive.