POST /v1/brands/generate endpoint returns a 202 Accepted immediately without the final assets. Nomiq delivers those assets by sending an HTTP POST request to your configured webhook endpoint the moment a job completes or fails. You must implement a webhook receiver to build a fully functional integration.
Event Types
Nomiq dispatches two event types for generation jobs. Every webhook request body contains a top-leveltype field you can use to route handling logic.
Example Webhook Payload
The following shows a representativegeneration.success payload. The data.assets object contains the deliverables you requested from the Generation API.
generation.failed payload omits the assets object and instead includes an error field:
Security & Signature Verification
Every webhook request Nomiq sends includes aNomiq-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your unique Webhook Secret. You must verify this signature on every incoming request before processing the payload — without it, a malicious actor could POST arbitrary data to your endpoint.
1
Retrieve Your Webhook Secret
Navigate to Workspace Settings → Webhooks in the Nomiq Dashboard. Your Webhook Secret is displayed here (format:
whsec_abc123). This secret is distinct from your API key — do not expose it in client-side code or commit it to source control. Store it as an environment variable (e.g., NOMIQ_WEBHOOK_SECRET).2
Compute the Expected HMAC-SHA256 Signature
Using the raw, unparsed request body bytes (not a re-serialized JSON object), compute an HMAC-SHA256 digest keyed on your Webhook Secret. Compare the resulting hex string to the value in the
Nomiq-Signature header. Ensure you parse the body as raw bytes — parsing to JSON and re-serializing can alter whitespace and break the signature check.3
Compare Signatures Using a Constant-Time Function
Always use a constant-time comparison function (such as
crypto.timingSafeEqual in Node.js or hmac.compare_digest in Python) when checking the signatures. Standard string equality operators (===, ==) are vulnerable to timing attacks that could allow an attacker to forge a valid signature through repeated probing.Retry Behavior
Nomiq expects your endpoint to respond with an HTTP2xx status code within 5 seconds. If your server returns a 4xx or 5xx response, or does not respond within the timeout window, Nomiq treats the delivery as failed and initiates an exponential backoff retry strategy. After four consecutive failures, the event is marked as undeliverable and no further retries are attempted.
Testing Webhooks Locally
Before deploying to production, you can verify your webhook handler works correctly by forwarding Nomiq’s test events to your local development server.1
Expose Your Local Server
Use a tunneling tool such as ngrok or localtunnel to create a publicly reachable HTTPS URL pointing at your local server. For example:Copy the generated HTTPS URL (e.g.,
https://a1b2-203-0-113-42.ngrok-free.app).2
Register the Endpoint in Nomiq
In the Nomiq Dashboard, navigate to Workspace Settings → Webhooks → Add Endpoint. Paste your full webhook URL (e.g.,
https://a1b2-203-0-113-42.ngrok-free.app/api/nomiq/webhook) and save it. Nomiq will display your Webhook Secret on this page — copy it into your environment variables before starting your local server.3
Send a Test Event
On the Webhooks settings page, click Send Test Event next to your registered endpoint. Nomiq dispatches a synthetic
generation.success payload to your URL with a valid Nomiq-Signature header. Check your local server logs to confirm the payload was received and the signature was verified correctly. If the signature check fails, ensure you are reading the raw request body bytes rather than a parsed JSON object.Next Steps
Generation API
Dispatch the async brand generation jobs whose results you’ll receive here via webhook.
Errors
Review all possible error codes and HTTP status responses you may encounter in your integration.