Setting Up Webhooks

Webhooks let Alpha Insights send your profit, sales, and expense data to an external URL on a schedule. You configure a single endpoint and choose how often to send: daily, weekly, or monthly. The payload is a JSON object containing date-bounded summaries and (optionally) full order and expense rows for the period.

How Alpha Insights Webhooks Work

Webhooks are scheduled exports, not real-time event notifications:

• You set one Webhook URL and one Schedule (Daily, Weekly, or Monthly).
• A recurring job runs at roughly 1am in your site’s local time each day. Whether it actually sends depends on the schedule:
• Daily – Every run sends data for yesterday (one day).
• Weekly – Only on Mondays; sends data for last week (Monday–Sunday).
• Monthly – Only on the 1st of the month; sends data for last month.
• Each run sends a single HTTP POST with a JSON body to your URL. The same payload structure is used every time; only the date_from and date_to (and the data inside) change for the selected period.

There are no per-order or per-event webhooks (e.g. no “order created” or “low profit alert” triggers). Everything is batch by date range.

Where to Configure

1. Go to Alpha Insights → Settings.
2. Open the Integrations tab and find the Webhooks section.
3. Enter your Webhook URL (the endpoint that will receive the POST).
4. Choose Schedule Webhook Export: Don’t Schedule Export, Daily, Weekly, or Monthly.
5. Optionally enable Enable Logging to log webhook runs and responses for debugging.
6. Click Save. If a schedule is selected, the next run will occur at the next 1am (and then only on the correct day for weekly/monthly).

Test Webhook

The Test Webhook button sends one immediate POST to your URL with the same JSON structure as the scheduled export. For the test, no date range is passed to the data warehouse, so the payload uses the warehouse’s default date range (typically a recent period up to “today”). The response from your endpoint is shown in the browser (e.g. success flag and response code). Use this to confirm the URL is reachable and that your endpoint accepts the payload.

Payload Structure

Every webhook request is:

• Method: POST
• Headers: Content-Type: application/json; charset=utf-8
• Body: A JSON object with the following top-level keys.

Top-level keys

• date_from – Start of the period (Y-m-d).
• date_to – End of the period (Y-m-d).
• sales_data_summary – Order totals for the period (same structure as the “orders” totals from the data warehouse). Includes keys such as total_order_count, total_order_revenue, total_order_revenue_ex_tax, total_order_cost, total_order_profit, average_order_value, average_order_margin, total_freight_recovery, total_freight_cost, total_payment_gateway_costs, and other order metrics.
• expense_data_summary – Expense totals for the period. Includes total_amount, total_amount_paid, average_expenses_per_day, and related expense metrics.
• store_profit_summary – Store profit for the period (order profit minus expenses). Includes total_store_profit, average_store_margin, daily_average_store_profit, and related fields.
• orders – An object keyed by order ID. Each value is one order’s data for the period: revenue, cost, profit, margin, date, status, payment gateway, shipping, product/cost breakdown, etc. The webhook uses data_table_limit with no limit for orders and expenses, so all orders in the range are included.
• expenses – An array of expense rows for the period. Each row includes fields such as title, date_created, date_paid, amount_paid, expense_type, recurring_expense, is_paid, and related metadata.

Exact keys and nesting may vary with your data warehouse and report builder; the structure above matches what the webhook code sends. You can inspect the Webhook Test Data Output on the same settings page to see a live example for your site.

After Saving

• Next Scheduled Sync – Shown on the settings page when a schedule is set; indicates when the next webhook run is due.
• Last successful webhook – Stored and displayed after a run returns a 200 response; useful to confirm the schedule is firing and the endpoint is responding.

Troubleshooting

• Webhook never runs – Ensure a schedule other than “Don’t Schedule Export” is saved. The job runs at ~1am site time; for Weekly only Mondays send; for Monthly only the 1st sends. Check that Action Scheduler (or your cron) is running.
• URL not receiving data – Verify the URL is correct and reachable from the server (no typo, HTTPS if required). Use “Test Webhook” and check the response. Enable logging and review the webhook log for errors or non-200 responses.
• Endpoint returns an error – Your endpoint should respond quickly (e.g. within a few seconds) and return HTTP 200 on success. Non-200 responses are logged; the last successful run time is only updated when the response is 200.