Webhook

Kanorio can notify your system in real-time when specific events occur on your website: order payments, shipment updates, form submissions, sending domain issues, quota alerts, or traffic milestones. By connecting to Zapier, Make, n8n, or your own custom code, you can automatically write data to spreadsheets, forward notifications to team chat groups, create support tickets, or sync with your ERP or CRM.

You can configure this in the Technical Settings section of your website console under the "Integrations" tab. Webhooks are a Business plan feature; only the website owner and admins can add or manage them. Other members cannot view URLs, secret keys, or delivery logs.

Adding a Webhook

1. Create a receiving URL on your destination platform. For example, choose "Catch Hook" in "Webhooks by Zapier" on Zapier, "Custom webhook" in "Webhooks" on Make, or add a "Webhook" node in n8n. The URL must start with https://.
2. Go to "Technical Settings" in your console and switch to the "Integrations" tab.
3. Click "Add Webhook" and paste your URL. You can give it a recognizable name, such as "Zapier Order Workflow".
4. Click "Add Webhook". The screen will display the "Signing Secret" for this endpoint. If you need to verify the request source, copy this and set it up in your receiving end (see "For Engineers" below).
5. Click "Send Test". When your receiving end receives a "Kanorio Test Event" and the screen shows the response status code and latency, the connection is successful.

You can add up to 5 Webhooks per website.

Selecting Events to Send

After expanding each endpoint, you can configure "Subscribed Events":

• All Events (Default): Sends all current events and automatically sends any new events added in the future.
• Specific Events: Select only the events you need and click "Save Subscription".

Currently supported events (see "Event Reference" at the end for field details):

Webhook delivery depends solely on these subscription settings. While individual scenario panels in Automations may show "N endpoints subscribed" or "Not connected," the actual control is here, not in Automations.

Webhooks do not replace your notification emails. After adding a Webhook, notification emails sent to the owner (e.g., new orders and form submissions) will still be sent. Team emails for shipment updates are disabled by default. To toggle team emails, please configure them in "Automations".

When Delivery Fails

• If the receiving end responds with an error (HTTP 429 or 5xx) or fails to respond within 8 seconds, Kanorio will automatically retry: after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, 24 hours, and another 24 hours—a total of 8 retries over approximately two and a half days.
• If the receiving end responds with other 4xx errors (e.g., 404, 401), it indicates a configuration issue, and no retries will occur.
• If the receiving end responds with 410 Gone, it indicates you no longer wish to receive notifications, and the endpoint will be paused immediately.
• If 3 consecutive notifications fail (all retries exhausted), the endpoint will be automatically paused to prevent continuous delivery to an invalid URL. The owner and admins will be notified.
• Once you confirm the receiving end is back to normal, expand the endpoint, click "Send Test", and then click "Re-enable" after a successful test.

Expand any endpoint to see "Recent Deliveries": event, result, HTTP status, and time. Expand each entry to view attempt counts, latency, next retry time, and error reasons. Notifications within the last 7 days can be "Viewed" to see the payload or "Resent" to try again. Resending uses the same delivery ID, which the receiving end can use for deduplication.

"Send Test" does not count toward failure limits, so feel free to use it for troubleshooting.

If Your Receiving End Has a Firewall

Kanorio sends Webhooks from fixed IPs. If your receiving end only allows whitelisted sources, please add all three of the following IPv4 addresses (initial delivery, tests, and manual resends come from the first two; automatic retries come from the third):

Whitelisting is an extra layer of protection and cannot replace signature verification: please always verify the X-Kanorio-Signature (see "For Engineers" below). If IPs need to change, we will announce it here and keep both old and new IPs running for a period before removing the old ones.

For Engineers

Request Format

Each notification is a POST request with Content-Type: application/json and the following headers:

Any 2xx response from the receiving end is considered a success; the response body is ignored. Please respond within 8 seconds. If longer processing is needed, return 200 first and process asynchronously. Kanorio does not follow redirects; 3xx responses are treated as failures.

Common Structure

All event JSONs share the same shell, so the receiving end only needs to be configured once:

{
  "version": "1",
  "id": "3f9c2a…",
  "event": "ec.order.paid",
  "occurredAt": "2026-09-29T12:00:00.000Z",
  "websiteId": "cmk…",
  "title": "New order #1024, NT$1,280",
  "summary": "'My Store' received a paid order.",
  "fields": [{ "label": "Order ID", "value": "#1024" }],
  "data": { "…": "Varies by event, see reference below" },
  "actionUrl": "https://app.kanorio.com/store/transactions?tx=…"
}

Event Reference

Below are the data fields for each event. "Nullable" means the field may be null.

ec.order.paid Order Paid

Sent when a buyer completes payment; once per order.

ec.shipment.statusChanged Shipment Update

Sent when a shipment enters shipped, arrived, delivered, or exception status; once for each status change per shipment.

customers.form.submitted Form Submission

Sent when a visitor submits a form and passes spam checks; once per submission.

answers[] items:

customers.sendingDomain.degraded Sending Domain Degraded

Sent when a verified custom sending domain fails verification; once per day per domain.

customers.messagingQuota.alert Messaging Quota Alert

Sent when quota status changes.

site.analytics.milestone Traffic Milestone

Sent when cumulative site views cross a milestone; once per milestone.

customers.teamDestination.disabled Integration Paused

Sent when a Webhook endpoint is automatically paused (consecutive failures or 410 response). Sent only to other healthy endpoints.

team.test Test Event

Sent when "Send Test" is clicked; once, no retries, not logged in delivery history.

Verifying Requests from Kanorio

Verification steps:

1. Extract t and all v1 from X-Kanorio-Signature.
2. Concatenate t, a period, and the raw request body (unparsed, re-serialized), e.g., 1790000000.{"version":"1",…}.
3. Compute HMAC-SHA256 (hex) of the string using the signing secret and compare with any v1. Accept only if they match.
4. Reject requests with timestamps older than 5 minutes to prevent replay attacks. Retries and resends use current timestamps, so no need to relax this limit.

Node.js example:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = header.split(",").map((part) => part.split("="));
  const t = parts.find(([key]) => key === "t")?.[1];
  const signatures = parts.filter(([key]) => key === "v1").map(([, value]) => value);
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return signatures.some(
    (v1) => v1.length === expected.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1))
  );
}

Services like Zapier, Make, and n8n usually don't support custom verification logic; their receiving URLs contain random paths, so verification is generally not required.

Rotating Signing Secrets

Secrets can be viewed by expanding the endpoint in the integration list and clicking "Show". If you suspect a leak, click "Generate New Secret":

• The old secret remains valid for 24 hours. During this time, each request will include both new and old signatures (two v1s); either one matching is sufficient.
• Please update your receiving end with the new secret within 24 hours. The panel will show the expiry time of the old secret.
• Clicking "Generate New Secret" again within 24 hours will immediately invalidate the previous old secret.

Related Docs

• Developer
• Automations
• Records: View every notification sent to customers and team
• Pricing Comparison