Skip to content
Browse documentation

Webhooks & events

There are two distinct mechanisms to understand:

  1. Inbound gateway webhooks — payment providers calling us to confirm payments and subscription changes. These are real, verified, and drive order/subscription state.
  2. Outbound store events: the activity your store emits (orders, sign-ups, product views). These flow through the store events pipeline to the destinations you enable. A destination can be a marketing tool (Klaviyo, Meta, GTM, Mixpanel, Twilio) or your own webhook URL. See Analytics & events for the full picture.

Inbound gateway webhooks

Payment providers notify NanoSite of events (payment succeeded, refund, subscription renewed) at a single verified endpoint:

POST /api/webhooks/:provider

The raw request body is read before JSON parsing so the provider's signature can be verified against the exact bytes. The flow is:

  1. Parse the payload just enough to find which store it belongs to.
  2. Load that store's provider config.
  3. Verify the signature (Stripe signing secret / PayPal webhookId / PayFast source-IP + MD5).
  4. Apply the event idempotently to the order or subscription.

An unknown provider is rejected; a payload that can't be tied to a store is acknowledged as a no-op. Event routing carries tenantId:orderId in the provider's metadata so events land on the right store and order.

Stripe events consumed

Stripe endpoints are registered automatically, subscribed to:

payment_intent.succeeded
payment_intent.payment_failed
charge.refunded
checkout.session.completed
invoice.paid
invoice.payment_failed
customer.subscription.updated
customer.subscription.deleted

These drive: order finalize on capture, cancel on failure, refund on charge.refunded, and subscription lifecycle sync (created → renewed → payment_failed / updated / canceled). Handling is idempotent, so a redelivered event never double-applies.

PayPal verifies PAYMENT.CAPTURE.* events against its webhookId; PayFast verifies the ITN callback by source-IP allowlist plus an MD5 signature.

Enabling subscriptions: because renewals arrive only by webhook, a store must have its Stripe webhook signing secret configured before it can sell subscription products.

Outbound store events

Your store emits a canonical set of commerce events once, and the platform fans them out to every destination you enable under Add-ons → Marketing. Destinations include Facebook/Meta, Google Tag Manager, Klaviyo, Mixpanel, Twilio, and a generic Webhook.

To receive events on your own server, or in Zapier, Make or n8n, enable the Webhook destination. Enter your https:// endpoint URL and save; we create the signing secret for you. Every event is then POSTed to that URL as JSON, signed per the Standard Webhooks spec. A delivery that does not get a 2xx response is retried with backoff. Setup, signature verification and retries are under Analytics & events → Webhook destination, and every event's fields are in the Webhook events reference.

The canonical event taxonomy is:

product_viewed, product_added_to_cart, checkout_started,
order_placed, order_fulfilled, order_refunded, order_cancelled,
customer_registered, customer_identified, newsletter_subscribed, custom
  • Authoritative order_* events are emitted server-side from verified checkout/payment code — they can never be spoofed from a browser.
  • Browsing events (product_viewed, product_added_to_cart, checkout_started) and custom are not emitted automatically. Only the browser sees these actions, so they enter the pipeline only when your storefront sends them with trackEvent / useTrackEvent.

The full pipeline is documented under Analytics & events. That covers sending events from your own frontend, the webhook payload, running your own browser SDK, and how consent is enforced.