Dataset Export Async

Queue a dataset export with a webhook to receive the result asynchronously. This endpoint initiates an asynchronous data export process. The export is processed in the background, and once complete, your webhook will be called with the results. ## Request Flow 1. Submit your export request with dataset query and webhook URL 2. Receive immediate 201 response confirming the export was queued 3. Export is processed asynchronously (may take several minutes for large datasets) 4. Your webhook is called when the export completes ## Webhook Response Format Once the export is complete, your webhook will receive a POST request with this payload: ```typescript { queryUUID: string // Unique identifier for this export request name: string // The name you provided for this export format: 'csv' | 'jsonl' // The format you requested payload: DatasetPayload // The original query payload you submitted gcsBlob: { // Information about the exported file url: string // Signed download URL (valid for 30 days) expires: string // ISO date string when URL expires timeTakenMs: number // Processing time in milliseconds numberRows: number // Number of rows in the exported data } requestedOn: Date // When the export was originally requested completedOn: Date // When the export was completed } ``` ## HMAC Signature Verification To verify the authenticity of webhook calls, compute the HMAC signature of the original request payload using your API key and compare it to the hmacSignature field in the webhook response. ### Node.js Example: ```javascript const crypto = require('crypto'); // Verify webhook authenticity function verifyWebhook(originalPayload, receivedSignature, apiKey) { const hmac = crypto.createHmac('sha256', apiKey); hmac.update(JSON.stringify(originalPayload)); const computedSignature = hmac.digest('hex'); return computedSignature === receivedSignature; } // Usage in your webhook handler app.post('/your-webhook', (req, res) => { const { payload } = req.body; const hmacSignature = req.get('SHA256-HMAC-Signature'); const isValid = verifyWebhook(payload, hmacSignature, 'your-api-key'); if (!isValid) { return res.status(401).send('Unauthorized'); } // Process the webhook... res.status(200).send('OK'); }); ``` ## Error Handling - **400 Bad Request**: Invalid webhook URL (must be HTTPS, no localhost/private IPs) - **403 Forbidden**: Invalid API key or insufficient permissions - If the export fails during processing, your webhook will not be called ## Requirements - Valid API key in `x-api-key` header - QueryBuilder product subscription OR query must include a report tag filter - Webhook URL must be HTTPS and publicly accessible (no localhost/private networks) - Your webhook endpoint should respond with 2xx status to confirm receipt ## Important Notes - The download URL expires in 30 days - ensure you download the file promptly - Large exports may take several minutes to complete - The queryUUID can be used to match requests to responses for tracking - Files are compressed with gzip for efficient transfer