Kanorio

Webhook Setup and Management

About 6 minIntermediate

When events occur on your website—such as a customer completing a payment, a package shipping or arriving, a visitor submitting a contact form, a domain verification failure, or hitting a traffic milestone—Kanorio can proactively send that data to your specified URL in real-time via Webhook.

By connecting Webhooks to Zapier, Make, n8n, or your own custom system, you can automatically sync new orders to Google Sheets, forward form submissions to your team's Slack/Discord/Telegram groups, create support tickets, or sync data with your company's ERP and CRM.

If you are the engineer building the receiving endpoint: This guide covers dashboard settings, event subscriptions, retry rules, and troubleshooting. For HTTP Headers, X-Kanorio-Signature verification code, and full JSON field specifications for all 8 events, please refer to Webhook Events and Signature Verification.

Before You Start

  • Location: Go to "Website Settings › Developer › Webhooks" in your dashboard.
  • Endpoint Limit: All plans (including Free, Pro, and Business) allow up to 10 Webhook endpoints per website.
  • Role Permissions: Only the Owner and Admins can add, test, modify subscriptions, view payload content, manually retry, and display/rotate signature keys. Other team members can only see the endpoint's display name and status; they cannot see the URL, keys, or delivery logs.

Adding and Testing a Webhook (5 Steps)

1. Get an HTTPS URL from your receiving tool

Open your receiving tool, create a Webhook receiver, and copy the URL (the URL must start with https:// and cannot be localhost or an internal network address):

  • Zapier: Create a new Zap, select "Webhooks by Zapier" as the Trigger → "Catch Hook" as the Event, and copy the generated Webhook URL.
  • Make: Create a new Scenario, select "Webhooks" as the first module → "Custom webhook", and copy the URL.
  • n8n: Add a "Webhook" node, set HTTP Method to POST, and copy the Production/Test URL.
  • Custom System: Have your engineer provide an https:// URL capable of receiving POST JSON requests.

2. Add the endpoint in Kanorio

Go to "Website Settings › Developer › Webhooks", click "Add Webhook", paste the URL you just copied, enter a recognizable display name (e.g., "Zapier Order Sync" or "Make Form Forwarding"), and click "Add Webhook".

3. Copy or save the signature key

Once created, the dashboard will display the "Signature Key" unique to this endpoint (starting with whsec_):

  • If using Zapier, Make, or n8n: These tools usually include a random key in the URL path, so signature verification is typically not required. You can simply click "Done".
  • If using a custom server: Copy this signature key and provide it to your engineer to implement signature verification. You can view it again by expanding the endpoint in the list and clicking "Show", or rotate it by clicking "Generate New Key".

4. Click "Send Test" to verify connectivity

Expand the newly created endpoint in the list and click "Send Test". The system will immediately send a test event (team.test):

  • If the screen shows "Test Successful (HTTP 200, took X ms)" and your Zapier/Make/server receives the test data, the connection is successful.
  • "Send Test" does not write to official delivery logs and does not count toward consecutive failure limits, so feel free to use it as needed during troubleshooting.

5. Adjust subscribed events (Optional)

New endpoints are set to subscribe to "All Events" by default. If you only want this URL to receive specific notifications (e.g., only "Order Paid"), see the next section.

Selecting Subscribed Events

Expand any endpoint in the list and use the "Subscribed Events" section to choose:

  • All Events (Default): All currently supported events will be sent, and any future events added by Kanorio will be included automatically.
  • Specific Events: Select only the events required for this endpoint (at least one must be selected) and click "Save Subscription" to apply changes immediately.

We currently support the following production events and 1 test event (for JSON field details, see Webhook Events and Signature Verification):

Event NameWhen is it sent?Event Code
Order PaidWhen the buyer completes payment and the order is officially created (sent once per order)ec.order.paid
Shipment Status ChangedWhen a shipment enters a status of shipped, arrived at store, delivered, or delivery exceptionec.shipment.statusChanged
Form SubmittedWhen a visitor submits an online form and passes the anti-spam check (includes form filler info and complete answers for every question)customers.form.submitted
Entitlement Granted/RevokedWhen a student gains or loses access to a course or download package due to purchase, free claim, or manual adjustmentdeliverables.entitlement.granted / revoked
Unit CompletedWhen a student completes a unit within a course (sent once per student per unit)deliverables.progress.unit_completed
Course CompletedWhen a student meets the completion criteria for a course (sent once per student per course)deliverables.progress.completed
Quiz AttemptedWhen a student submits a quiz (includes score and pass/fail status)deliverables.quiz.attempted
Certificate IssuedWhen a student receives a certificate (includes certificate number and issue date); once per student per coursedeliverables.certificate.issued
Collection Item ChangedWhen a single item in a Collection is created, updated as a draft, published, unpublished, or deletedcollections.item.created / updated / published / unpublished / deleted
Collection Batch ChangedWhen items are bulk-saved, imported via CSV/JSON, or written to a collection via API (sent as a single event)collections.items.bulk_changed
Translation Published/RemovedWhen a specific piece of content in a Multilingual Site is published or removed individually (e.g., saved after correction, API write, or auto-translation after source change); not sent individually during full-site translationcontent.translation.published / deleted
Locale Published/Unpublished/UpdatedWhen a locale is published (full-site translation complete or manual publish), removed, disabled, or when the URL prefix, auto-translate toggle, order, or primary language is updatedlocalization.locale.published / unpublished / updated
Full-Site Translation Completed/FailedWhen a full-site translation initiated by adding a language or "re-run missing" finishes (includes counts for translated, skipped, and failed items)localization.job.completed / failed
Sending Domain InvalidatedWhen the DNS verification for your custom sending domain fails (max once per day per domain)customers.sendingDomain.degraded
Messaging Quota AlertWhen the current billing period's email quota is exhausted, auto-top-up is triggered, auto-top-up reaches the limit, or top-up payment failscustomers.messagingQuota.alert
Storage Quota AlertWhen storage is near full, full, auto-top-up is triggered, auto-top-up reaches the limit, or top-up payment failssite.storageQuota.alert
Annual Renewal ReminderBefore an annual plan renews, if there are annual add-ons or unsettled add-on/platform fees (previews the total combined charge)site.subscription.upcomingRenewal
Add-on Price Change NoticeBefore an add-on's pricing is adjusted (at least 30 days in advance)site.subscription.addOnPriceChange
Traffic MilestoneWhen the site's cumulative unique visitors exceed 100 or 500site.analytics.milestone
Integration PausedWhen a Webhook endpoint is automatically paused by the system due to consecutive failures (notifies other healthy endpoints; not sent to the paused endpoint)customers.teamDestination.disabled
Access RequestWhen a team member encounters insufficient permissions in the dashboard and submits an Access Request (sent once per request)team.accessRequest.created
Test EventWhen "Send Test" is clicked in the panelteam.test

Webhooks vs. Team Notification Emails

  • Independent Management: Whether a Webhook is sent depends solely on the subscription settings for each endpoint under "Website Settings › Developer › Webhooks". In "Automations › Settings", you can see if "Send Webhook" shows "N endpoints subscribed" or "Not connected" for reference, but the actual toggles are managed on the Webhooks page.
  • Does not replace Team Emails: Adding a Webhook does not stop the standard notification emails (e.g., new orders, form replies) sent to the website owner or team members. To disable team emails and use only Webhooks, go to "Store Notifications" or "Form Confirmation Emails" and toggle off the team email settings.
  • No impact on email quotas: Webhooks are pushed directly to external URLs via HTTPS and do not consume your website's monthly email sending quota.

Viewing Logs, Manual Retries, and Automatic Pausing

Viewing recent deliveries and "Retry"

Expand any endpoint; the "Recent Deliveries" section below lists the last 10 notifications, including event name, status (Sent, Failed, Processing), HTTP status code, and timestamp. Click a record to view attempt count, duration, next retry time, and failure reason:

  • View Content (7-day retention): You can click "View Content" within 7 days of the notification to see the full JSON payload sent.
  • Manual Retry (7-day retention): If the receiver was temporarily down or your flow settings were just fixed, you can click "Retry" to push the notification again within 7 days. Manual retries use the same notification ID (making it easier for the receiver to deduplicate), and if a manual retry fails, it will not trigger background retries or count toward the automatic pause limit.

Automatic retries and pausing on failure

If your receiver does not respond correctly, the system handles it based on the response status:

  1. Automatic Exponential Backoff (Up to 8 attempts, ~2.5 days): If the receiver fails to respond within 8 seconds, encounters a network error, or returns HTTP 429 (Too Many Requests) or 5xx (Server Error), Kanorio will automatically retry in the background: 1 min → 5 mins → 30 mins → 2 hrs → 8 hrs → 24 hrs → 24 hrs, for a total of 8 attempts including the initial send.
  2. Non-retryable errors (3xx and other 4xx): If the receiver returns a redirect (301, 302, etc.) or a configuration error (e.g., 400, 401, 403, 404), the system will not retry and will count it as 1 failed delivery.
  3. Immediate Pause (410 Gone): If the receiver returns 410 Gone, it indicates the URL is explicitly disabled, and the system will immediately pause the endpoint.
  4. Automatic pause after 3 consecutive failures: If an endpoint fails 3 consecutive notifications (e.g., all 8 retries exhausted, or 3 consecutive 404 errors), the system will mark the endpoint as "Consecutively Failed, Paused", stop further pushes, and send a platform notification and email to members with "Manage Integrations" permissions (Owner, Admins, and custom roles with this permission).
  5. How to re-enable: Once you have fixed the receiver (or Zapier/Make flow), return to "Website Settings › Developer › Webhooks", expand the endpoint, click "Send Test" to verify the response, and then click "Re-enable" to resume pushes (failure count will reset to zero).

Common failure reasons and troubleshooting

If you see a failure message in "Send Test" or "Recent Deliveries", refer to the table below:

Failure Reason in DashboardWhat does it mean?Recommended Action
Receiver timed out after 8 secondsThe receiver took too long to process the requestAsk your engineer to update the receiver to "return a 200 OK immediately after validating the request, then process time-consuming tasks (like database writes or emails) in the background"
Receiver returned a redirect, Kanorio does not followThe URL returned a 301, 302, 307, or 308Commonly caused by a missing or extra trailing slash / or a domain change. Update the Webhook URL directly to the final https:// URL
Receiver's SSL certificate is invalid or expiredThe HTTPS certificate for the URL is not installed correctly, expired, or self-signedUpdate the SSL/TLS certificate on your server (must be issued by a trusted public certificate authority)
Domain for this URL cannot be foundDNS cannot resolve the domainCheck for typos in the Webhook URL and verify that the domain's DNS A/CNAME records are active
Cannot connect to the receiverThe receiver server is down or blocked by a firewallEnsure the server is running and the firewall allows the two static Kanorio source IPs listed below
Receiver rejected the request (HTTP 401 / 403)Authentication or signature verification failedIf using a custom server, ensure the signature key matches the one in the Kanorio panel and that the raw body is used for verification
Receiver could not find this URL (HTTP 404)The URL path does not exist, or the Zapier/Make flow is not activeCheck for URL typos. If using an n8n Test URL or Make, ensure the listener is active or the flow is officially enabled in their interface
Receiver temporarily limited request frequency (HTTP 429)The receiver (or Zapier/Make free tier) reached the rate limitThe system will automatically schedule a retry. If this happens frequently, check your plan limits or increase the rate limit
Receiver encountered an error (HTTP 5xx)Internal server error (e.g., 500, 502, 503)Check your server's error logs, fix the issue, and click "Retry" in Kanorio

If your receiver has a firewall (Static IP Whitelist)

All Kanorio Webhook requests (including initial pushes, test sends, manual retries, and background retries) are sent from the following two IPv4 addresses in rotation. If your server or firewall has an IP whitelist, please allowlist both IPs:

Static Egress IPs (IPv4)
137.184.250.60
167.99.28.231

Security Note: IP whitelisting is an additional network-layer defense and cannot replace signature verification. Always verify the X-Kanorio-Signature on your custom receiver. If we need to add or change egress IPs in the future, we will announce it on this page in advance and maintain a parallel period for old and new IPs.

Handoff to engineers (Signature Keys and Website ID)

If you are working with an internal or outsourced engineer to develop the receiving program, you only need to provide two pieces of information from the dashboard and a link to the Webhook Events and Signature Verification technical documentation:

  1. Endpoint "Signature Key (whsec_...)": Expand the endpoint in "Website Settings › Developer › Webhooks" and click "Show" in the Signature Key section to copy it.
    • If you suspect a key leak or need periodic rotation: Click "Generate New Key". After rotation, the old key remains valid for 24 hours (during which time every request will include signatures calculated with both keys), giving your engineer 24 hours to update server settings with zero downtime. If you click "Generate New Key" again within those 24 hours, the previous key will be invalidated immediately.
  2. Website ID (websiteId): If your server receives Webhooks for multiple Kanorio websites, you can use the websiteId field in the JSON to distinguish them. You can copy the websiteId at the very bottom of the "Website Settings › General" page.

URLs, signature keys, and delivery content from the last 7 days are encrypted at rest using Google Cloud envelope encryption. Every time a key is displayed or content is viewed in the dashboard, an audit log is generated (see How Keys and Credentials are Stored).

Frequently Asked Questions

No. Webhooks are supported on Free, Pro, and Business plans with up to 10 endpoints and granular event filtering. Changing or canceling your plan will not affect your configured URLs, display names, event subscriptions, or signature keys.

When a receiver takes longer than 8 seconds to respond, experiences a network blip, or someone clicks "Retry" in the dashboard, the same notification may be sent again. Retries and manual retries include the exact same notification ID (Header X-Kanorio-Delivery and JSON id). Please have your engineer or automation flow use this ID to check for duplicates.

Kanorio currently pushes standard JSON-formatted generic Webhooks. To forward data to Slack, Discord, Telegram, Microsoft Teams, or Google Sheets, we recommend connecting the Webhook to Zapier, Make, or n8n first, and letting them format and forward the data to your team's preferred communication tool.

You can refer to the full JSON examples for each event in Webhook Events and Signature Verification, or create a Webhook endpoint, click "Send Test", and once a real event occurs on your site (e.g., submitting a test form), click "View Content" under "Recent Deliveries" in the dashboard to see the actual JSON payload.