Skip to main content
Because brand generation is handled asynchronously by a computationally intensive AI Engine — taking between 3 and 10 seconds per job — the 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-level type field you can use to route handling logic.

Example Webhook Payload

The following shows a representative generation.success payload. The data.assets object contains the deliverables you requested from the Generation API.
A generation.failed payload omits the assets object and instead includes an error field:

Security & Signature Verification

Every webhook request Nomiq sends includes a Nomiq-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 HTTP 2xx 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.
Return 200 OK immediately — do not perform heavy processing before responding. Database writes, image transforms, and third-party API calls can easily exceed the 5-second timeout and trigger unwanted retries, causing duplicate processing on your end. Instead, persist the raw payload to a queue (e.g., Redis, BullMQ, SQS) inside your webhook handler, return 200 at once, and process the queued event in a background worker.

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.