Webhooks Reference | ListingRVA AI Docs

Webhooks

Webhooks let your server receive real-time notifications when image generation jobs complete on the ListingRVA AI platform. Available on the Pro plan only.

Overview

When an event fires, ListingRVA AI sends an HTTP POST request to your configured endpoint with a JSON body. Your endpoint must respond with a 2xx status within 5 seconds. There are no retries — if delivery fails the event is not resent.

Property	Value
Method	HTTP POST
Content-Type	application/json
Timeout	5 seconds
Signature header	X-Webhook-Signature
Retries	None

Register endpoint

Register a webhook endpoint via the API. The response includes a secret that is shown only once — store it securely, as it is used to verify all future deliveries.

# Register a webhook endpoint curl -X POST https://api.listingrvaai.com/api/webhooks \ -H "Authorization: Bearer <your-jwt-token>" \ -H "Content-Type: application/json" \ -d '{ "url": "https://yourapp.com/webhooks/listingrva", "events": ["image.generated"] }'

Webhook registration requires a valid JWT from an active Pro session. The secret is returned once in the registration response and cannot be retrieved again.

Signature verification

Every webhook request includes an X-Webhook-Signature header — a HMAC-SHA256 hex digest of the raw request body using your webhook secret. Always verify this before processing the event.

// Node.js const crypto = require('crypto'); function verifyWebhook(rawBody, signature, secret) { const expected = crypto .createHmac('sha256', secret) .update(rawBody, 'utf8') .digest('hex'); return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(signature) ); }

// PHP function verifyWebhook($rawBody, $signature, $secret) { $expected = hash_hmac('sha256', $rawBody, $secret); return hash_equals($expected, $signature); }

Always compare signatures using a timing-safe equality function (crypto.timingSafeEqual or hash_equals) to prevent timing attacks.

Manage webhooks

List, update, or delete registered webhooks via the API.

# List webhooks curl https://api.listingrvaai.com/api/webhooks \ -H "Authorization: Bearer <your-jwt-token>" # Update a webhook curl -X PUT https://api.listingrvaai.com/api/webhooks/<webhook-id> \ -H "Authorization: Bearer <your-jwt-token>" \ -H "Content-Type: application/json" \ -d '{"url": "https://yourapp.com/new-endpoint"}' # Delete a webhook curl -X DELETE https://api.listingrvaai.com/api/webhooks/<webhook-id> \ -H "Authorization: Bearer <your-jwt-token>"

image.generated

The only webhook event the platform currently fires. Sent when an image generation job completes successfully. The payload object contains the job result details.

{ "event": "image.generated", "payload": { "jobId": "<job-id>", "style": "hero_white_bg", "platform": "shopify", "imageCount": 1, "assetIds": ["<asset-id>"] }, "timestamp": "2026-05-18T10:00:00.000Z" }

Field	Description
event	Always `image.generated`
payload.jobId	Database ID of the completed job
payload.style	Image style key (e.g. hero_white_bg)
payload.platform	Target platform (shopify, amazon, etc.)
payload.imageCount	Number of images generated
payload.assetIds	Array of asset IDs — fetch full URLs via `GET /api/assets/:id`
timestamp	ISO 8601 datetime of the event