Dataset Webhook Export
This feature requires an active Query Builder subscription. Contact our sales team if you need access to this product.
Export datasets asynchronously and receive the results via webhook when processing is complete. This is ideal for large datasets that would timeout with synchronous requests, or when you want to process data in the background without maintaining an active connection.
The webhook export is perfect for:
- Large datasets with thousands of rows
- Scheduled or automated data exports
- Background processing workflows
- Integration with data pipelines
How It Works
- Submit Export Request: Send your dataset query along with a webhook URL
- Receive Confirmation: Get immediate 201 response with export queued
- Processing: Your export is processed asynchronously in the background
- Webhook Notification: Your endpoint receives the results when complete
Request Format
The request requires:
- dataset: Your query configuration (columns, filters, limits)
- webhookURL: HTTPS endpoint where results will be sent
- name: Descriptive name for your export
- format: Either ‘csv’ or ‘jsonl’
Webhook Response
When your export completes, you’ll receive a POST request with this payload:
Implementing Your Webhook Handler
Your webhook endpoint should handle the incoming POST request and verify the HMAC signature for security:
Security & Verification
Always verify the HMAC signature to ensure the webhook request is legitimate:
- Compute HMAC: Use your API key and the original request payload
- Compare Signatures: Match against the
hmacSignature
field - Reject Invalid Requests: Return 401 for signature mismatches
Important Notes
Download URLs expire in 30 days - make sure to download your files promptly after receiving the webhook notification.
- Processing Time: Large exports may take several minutes to complete
- File Format: Files are compressed with gzip for efficient transfer
- Webhook Requirements: Your endpoint must be HTTPS and publicly accessible
- Response Expected: Your webhook should respond with 2xx status to confirm receipt
- Tracking: Use the
queryUUID
to match requests with responses
Error Handling
If the export fails during processing, your webhook will not be called. Monitor your webhook endpoint for delivery failures.
Use Cases
Data Pipeline Integration
Scheduled Reports
Full Documentation
Find complete technical details in our API Reference.