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