Help CenterContact support
All Columna: Order Export & Sheets articles

How do I send scheduled exports to a webhook?

Updated

On this page
  1. Set it up
  2. What your endpoint receives
  3. Check the signature
  4. How the app treats your answer
  5. Verify it worked
  6. Change the URL, secret or header
  7. If an export keeps failing
  8. Troubleshooting

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

  1. In the app, open Settings and pick Scheduled email exports, then click Add scheduled export (or open an existing one).
  2. In File, enter a name and choose the template and file format.
  3. In Delivery, choose Webhook (HTTPS POST) under Deliver to.
  4. Endpoint URL: the full https:// address that receives the file, for example https://hooks.example.com/columna. A path and a query string are fine. Plain http:// and addresses on a private network are not accepted.
  5. 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).
  6. 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.
  7. Optional: if your endpoint wants an API key in a header, enter the header name in Custom header (optional), for example X-Api-Key or Authorization, and its Header value.
  8. If your endpoint allows only some addresses, allow the address shown there (“Columna sends from …”).
  9. Click Test connection to send a test request before saving.
  10. 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:

  1. Read X-Columna-Timestamp and X-Columna-Signature.
  2. 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.
  3. Compute the HMAC-SHA256 of timestamp + "." + body with your secret, using the body bytes exactly as received, before any JSON parsing.
  4. 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, 429 or 5xx, a timeout, or no connection: the app tries again a few minutes later.
  • 401 or 403: the export fails with “The endpoint refused the request”. Check the custom header and the secret.
  • 404 or 410: 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.

Built and supported by StoreFleet, Shopify app developers since 2021.