Skip to content
CMS Max Documentation

Webhooks

Send real-time notifications to external services when events happen on your site

What Are Webhooks?

Webhooks automatically send data to an external URL whenever something happens on your site — like a form submission or a new order. Instead of manually checking for updates, the external service receives the data instantly.

Common uses:

  • Send form submissions to a CRM (HubSpot, Salesforce)
  • Notify your team in Slack when an order is placed
  • Sync data with automation tools (Zapier, Make, n8n)
  • Feed submissions into a spreadsheet or database

Managing Webhooks

Navigate to Settings > Webhooks in the admin panel.

Webhooks list view showing active and archived entries

Creating a Webhook

  1. Click Create Webhook
  2. Fill in the configuration:
    • Name — A descriptive label (e.g. "Slack Order Notifications")
    • URL — The endpoint that will receive the data (provided by the external service)
    • Secret — Auto-generated. Share this with the receiving service if they verify signatures.
    • Events — Check which events should trigger this webhook (e.g. Form Submitted, Order Placed)
    • Active — Toggle off to temporarily pause deliveries without deleting the webhook
  3. Click Save

Create Webhook form with Events checklist

Advanced Settings

  • Timeout — How long to wait for a response (5–120 seconds, default 30)
  • Max Retries — How many times to retry if delivery fails (0–10, default 3)

Testing a Webhook

Click the play icon on any webhook in the list to send a test payload. Check the deliveries tab to see the result.

Viewing Delivery History

Click a webhook to view its delivery history. Each delivery shows:

  • Status — Success or Failed
  • Response Code — The HTTP status returned by the endpoint
  • Duration — How long the request took
  • Attempt — Which retry attempt this was

Click "View Details" on any delivery to see the full payload sent and the response received.

Webhook detail page with delivery history table

Archiving Webhooks

Instead of deleting, webhooks are archived (soft-deleted). Archived webhooks:

  • Stop receiving events immediately
  • Keep their delivery history intact
  • Can be restored later from the "Archived" filter

Archived webhooks filter showing soft-deleted entries

Automatic Behavior

Auto-Disable

If a webhook fails consistently (10+ consecutive failures), it will be automatically deactivated to prevent hammering a dead endpoint. You'll see it marked as inactive in the list. Re-activate it manually once the receiving service is back online.

Delivery Envelope

Every webhook delivery includes:

{
  "event": "form.submitted",
  "timestamp": "2026-04-01T12:00:00+00:00",
  "data": { ... }
}

The event field tells you what happened. The timestamp is when the event occurred. The data contains the event-specific payload.

Available when Ecommerce is active. data.customer.marketing_status says whether the customer wants your marketing emails, using Mailchimp member statuses: subscribed, transactional (bought at checkout and didn't opt in), unsubscribed (opted out in their account), or null when your checkout didn't ask (or, when the webhook is sent, the customer's email has changed since the order). data.customer.marketing_opt_in says whether consent was given on this order: true only when the checkbox was checked when the order was placed and it took effect (the status is subscribed), otherwise false. The checkbox starts checked, so true includes a box the customer left as it was; it doesn't mean they ticked it. A subscribed with false carries over an earlier opt-in, and a checked box next to unsubscribed (the address's owner had opted out) is false too; it's null when no status is reported. When a status is reported, data.customer.email_subscribed is true only for subscribed. Only Order Placed carries the order's choice; refund events carry no marketing_status, so don't use them to update a mailing list. Customer Marketing Preference Updated carries the customer's current choice. Apply events in timestamp order (an order's is when it was placed). See Checkout Settings.

Tip: For Mailchimp, set the member status only for unsubscribed (to unsubscribed). Send subscribed and transactional only as status_if_new, whatever marketing_opt_in says, so an existing contact keeps their status: one who unsubscribed through your newsletter's link stays unsubscribed even when they order again with the box still checked, and one who joined through your newsletter form stays subscribed. Treat a subscribed from Customer Marketing Preference Updated with source checkout_order the same way. Skip null.

Customer Marketing Preference Updated

A webhook subscribed to Customer Marketing Preference Updated receives a delivery when a customer turns your store on or off on the Email Preferences tab of their checkout account, when a signed-in customer subscribes at checkout, and when a guest orders with the box checked and the email of a verified account. Opt-outs are always delivered; an opt-in from the customer account is delivered only while Enable Marketing Opt-in is on and Ecommerce is active. The data holds the customer (email, email_subscribed and marketing_status, named as in Order Placed; no name or phone), the source (profile or checkout_order), changed_at, and the order_number when an order made the change. A change can occasionally be delivered twice; use changed_at to order deliveries. Webhooks subscribed only to Order Placed don't receive it.

Order Refunded

Available when Ecommerce is active. A webhook subscribed to Order Refunded receives a delivery each time an order is refunded or voided, so an order refunded in two parts sends two deliveries. The data holds the order (the same fields as Order Placed) and a refund section with the amounts returned to the payment method and to gift cards, whether it was a refund or a void, the reason, who issued it and when.

Tip: A delivery can arrive more than once (for example after a retry). To ignore repeats, treat data.order.id together with data.refund.sequence as the refund's identity.

Refunds and voids issued from the order page in the admin send this event, and so does a refund made in your PayPal account, once PayPal reports it. A refund made directly in another payment provider's dashboard doesn't.

Order Refund Failed

Available when Ecommerce is active. PayPal can accept a refund, which normally sends Order Refunded, and fail it later. A webhook subscribed to Order Refund Failed then receives a delivery with the same data as Order Refunded, where data.refund.status is failed. The customer didn't get that money back, and the order no longer counts it as refunded. The store's admin notification recipients get an email about it, and the order page shows a Refund failed notice.

Signature Verification

Each delivery includes an X-Webhook-Signature header containing an HMAC SHA256 signature. Use the webhook's secret to verify the payload hasn't been tampered with.

Each delivery also includes an X-Webhook-Id header. Automatic retries of a delivery send the same ID, so your service can ignore a delivery it has already processed.

Zapier Integration

For Zapier-specific setup, install the Zapier plugin from the Plugins page. See the Zapier setup guide for step-by-step instructions.

The Zapier app has no Order Refunded trigger. To act on refunds in Zapier, create a webhook subscribed to Order Refunded and point it at a Zapier Catch Hook URL.