Webhooks

Webhooks let you receive real-time notifications when specific events occur in Nova. Instead of polling the Nova API for changes, you register an endpoint on your server and Nova sends an HTTP POST request to that endpoint each time that a subscribed event occurs.

For example, you can use webhooks to:

• Detect when a new user registers for Nova on your hosting platform.
• Monitor AI credit consumption and respond when a user runs out of credits.
• Integrate Nova user activity data into your CRM, marketing automation tools, or analytics pipelines.

Register a webhook#

You can view and update your webhook configuration in the Partner Dashboard at White Labeling » Webhooks.

For each supported event type, you can configure the following values:

• Webhook URL — The HTTPS endpoint on your server that receives event payloads. Your server must accept requests from the public internet at this URL, and the URL cannot point to private or internal network addresses (for example, 192.168.x.x, 10.x.x.x, or localhost).
• API Key — A secret key that you choose. Nova will use this key to sign and authenticate incoming requests.

Supported events#

Nova webhooks support the following event types:

Webhook requests#

When a configured event occurs, Nova sends a standard HTTP POST request to the webhook URL that you specified. Each request includes headers for authentication and a JSON payload with details about the event and the user.

Request headers#

Nova sends the following headers with every HTTP POST request:

The request body is a JSON object containing the event type and the user’s current data. For more information, see Request body.

Request body#

Every POST request body includes the following fields:

For example:

{
  "event_type": "build_completed",
  "user_name": "Jane Smith",
  "user_email": "jane@example.com",
  "credit_used": 12,
  "total_projects": 3,
  "published_projects": 1,
  "last_login": "2026-05-14T06:30:00.000Z",
  "last_build": "2026-05-14T08:45:00.000Z",
  "free_or_paid": "paid",
  "paid_plan_name": "Pro",
  "has_connected_domain": "yes"
}

Verifying webhook requests#

Nova signs each payload using your API key as the secret.

To verify a request:

1. Read the raw request body before parsing it as JSON.
2. Read the signature from the X-Signature-SHA256 header and strip the sha256= prefix.
3. Compute an HMAC-SHA256 hash of the raw request body using your API key as the secret.
4. Compare the result to the stripped header value using a constant-time string comparison to prevent timing attacks. A match confirms that the request came from Nova.
5. Acknowledge the request immediately with a 2xx HTTP status code and process the payload asynchronously.

   Your endpoint should respond within three seconds to avoid triggering unnecessary retries. For more information, see Retries and timeouts.

Retries and timeouts#

Nova makes up to four delivery attempts in total (one initial attempt plus up to three retries).

4xx responses#

If Nova receives a 4xx response (for example, 400 Bad Request, 404 Not Found, or 401 Unauthorized), it treats the delivery as a permanent failure and does not retry. These responses indicate a configuration problem in your system.

5xx responses and network errors#

If Nova receives a 5xx response (for example, 500 Internal Server Error or 503 Service Unavailable) or encounters a network error (for example, a connection timeout), it treats the delivery as a temporary failure.

In this scenario, Nova retries the delivery using the following schedule:

If all delivery attempts fail, Nova logs the event for investigation.