How do I send scheduled exports to a webhook?
On this page
A scheduled export can send its file to your own HTTPS endpoint with a POST request: an ERP or warehouse system, an automation tool such as Make, Zapier or n8n, or a small script of your own. The file arrives every few hours, every day, week or month, or a few minutes after each new order. This is part of the Pro plan.
Set it up
- In the app, open Settings and pick Scheduled email exports, then click Add scheduled export (or open an existing one).
- In File, enter a name and choose the template and file format.
- In Delivery, choose Webhook (HTTPS POST) under Deliver to.
- Endpoint URL: the full
https://address that receives the file, for examplehttps://hooks.example.com/columna. A path and a query string are fine. Plainhttp://and addresses on a private network are not accepted. - Request body: choose JSON with the export name, period, order count and the file in base64, or The file itself, with its content type (see “What your endpoint receives” below).
- Optional: tick Sign each request and enter a Signing secret of 16 to 256 characters. Your endpoint uses the same secret to check that a request came from Columna (see “Check the signature” below). We recommend it.
- Optional: if your endpoint wants an API key in a header, enter the header name in Custom header (optional), for example
X-Api-KeyorAuthorization, and its Header value. - If your endpoint allows only some addresses, allow the address shown there (“Columna sends from …”).
- Click Test connection to send a test request before saving.
- Choose the schedule and the orders to include, then click Save in the bar at the top of the page.
When you test or save, the app sends a test request with the header X-Columna-Test: true and a small text file named .columna-connection-test.txt (in the JSON body, "test": true). Your endpoint must answer with a 2xx status. It can ignore test requests.
What your endpoint receives
Every request is a POST with these headers:
| Header | Value |
|---|---|
Content-Type |
application/json for the JSON body; the file’s type (for example text/csv) for the file itself |
User-Agent |
Columna-Webhook/1.0 |
X-Columna-Delivery-Id |
A new random id for every request |
X-Columna-Timestamp |
Unix time in seconds when the request was signed (only when signing is on) |
X-Columna-Signature |
sha256= and the hex HMAC-SHA256 signature (only when signing is on) |
X-Columna-Test |
true on a test request only |
Content-Disposition |
attachment; filename="..." when the body is the file itself |
| Your custom header | The value you entered |
The JSON body looks like this:
{
"export": { "id": "0b6c2f0e-8d7a-4c39-a1f4-5e2b7c9d3a10", "name": "Daily orders" },
"file": {
"name": "daily-orders-2026-10-23.csv",
"contentType": "text/csv",
"base64": "T3JkZXIsVG90YWwKIzEwMDEsMTIuMDAK"
},
"period": { "from": "2026-10-22T22:00:00Z", "to": "2026-10-23T22:00:00Z" },
"rowCount": 1,
"orderCount": 1,
"test": false
}
period gives the start and end of the orders in the file, in UTC. Decode file.base64 to get the file exactly as an email or an upload would carry it. Files are named after the export and the period and never repeat, so you can use the file name to spot a file you already processed.
Files larger than 20 MB are not sent: narrow the filters or choose a template with fewer columns. When there were no orders, nothing is sent.
Check the signature
With signing on, the signature is the HMAC-SHA256, keyed with your secret, of the timestamp, a dot (.) and the raw request body, as lowercase hex. To check a request:
- Read
X-Columna-TimestampandX-Columna-Signature. - Refuse the request if the timestamp is more than 5 minutes away from your clock. This stops someone from sending a captured request again later.
- Compute the HMAC-SHA256 of
timestamp + "." + bodywith your secret, using the body bytes exactly as received, before any JSON parsing. - Compare
sha256=plus your result with the header, using a constant-time comparison.
Node.js (Express):
const crypto = require('node:crypto');
const express = require('express');
const app = express();
const secret = process.env.COLUMNA_WEBHOOK_SECRET;
app.post('/columna', express.raw({ type: '*/*', limit: '30mb' }), (req, res) => {
const timestamp = req.get('X-Columna-Timestamp') ?? '';
const signature = req.get('X-Columna-Signature') ?? '';
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(401);
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(req.body).digest('hex');
const valid = signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!valid) return res.sendStatus(401);
if (req.get('X-Columna-Test') === 'true') return res.sendStatus(204);
// req.body is the file itself, or the JSON body: JSON.parse(req.body.toString('utf8'))
res.sendStatus(204);
});
app.listen(3000);
Python (Flask):
import hashlib
import hmac
import os
import time
from flask import Flask, abort, request
app = Flask(__name__)
SECRET = os.environ["COLUMNA_WEBHOOK_SECRET"].encode()
@app.post("/columna")
def columna():
timestamp = request.headers.get("X-Columna-Timestamp", "")
signature = request.headers.get("X-Columna-Signature", "")
body = request.get_data()
if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300:
abort(401)
expected = "sha256=" + hmac.new(SECRET, timestamp.encode() + b"." + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
abort(401)
if request.headers.get("X-Columna-Test") == "true":
return "", 204
# body is the file itself, or the JSON body: request.get_json()
return "", 204
How the app treats your answer
2xx: delivered.408,429or5xx, a timeout, or no connection: the app tries again a few minutes later.401or403: the export fails with “The endpoint refused the request”. Check the custom header and the secret.404or410: the export fails. Check the URL.- A redirect (
3xx): the app does not follow redirects. Enter the final URL. - Any other
4xx: the export fails.
Answer quickly: the app waits up to one minute for your response and reads at most 64 KB of it. Its content is never stored. Connections always use HTTPS with a certificate from a public certificate authority.
Verify it worked
- After Test connection you see “Test request delivered. Your endpoint answered with a success status.”
- After saving you see “Settings saved”. Click Send now in Status: your endpoint gets the file within a few minutes.
- The list of scheduled exports shows “Webhook:” and the endpoint’s host for this export.
Change the URL, secret or header
The signing secret and the header value are never shown again after saving. To keep them, leave the fields empty. If you change the host of the URL, enter them again: a saved secret is never sent to another host.
If an export keeps failing
While a scheduled export is failing, a red banner on the app’s Home and in Settings names it; click Open export to see the error. Your store’s contact email also gets one email about it, with what to check and a button that opens the export, a reminder every 24 hours while it lasts, and one more email when it works again.
Troubleshooting
“That host is private or reserved.” The app can only reach endpoints on the public internet. Enter your endpoint’s public URL.
“The endpoint’s TLS certificate could not be verified.” Self-signed certificates are not accepted. Use a certificate from a public certificate authority, such as Let’s Encrypt.
“The endpoint answered with a redirect.” Enter the address the redirect points to, often with or without www or a trailing slash.
“The export file is larger than 20 MB.” Narrow the orders with filters, choose a template with fewer columns, or send more often (for example every hour) so each file is smaller.