Skip to main content

Webhooks

Webhooks allow your app to receive real-time notifications when specific events occur within a SitePack store. Instead of polling the API for changes, SitePack will "push" data to your server via an HTTPS POST request.

How Webhooks Work​

  1. Subscription: You define the events (topics) you want to listen to in your app.json.
  2. Event Occurs: A merchant performs an action (e.g., a customer submits a form).
  3. Delivery: SitePack sends a signed JSON payload to your configured endpoint.
  4. Acknowledgement: Your server must respond with a 200 OK status code to acknowledge receipt.

The "Thin Payload" Strategy​

To ensure security and data privacy, SitePack webhooks use a Thin Payload architecture. Instead of sending all the resource data (which might contain sensitive PII), the webhook contains only the metadata and a link to the resource.

Example Payload​

{
  "uuid": "019eca47-221d-73c1-9c6c-c556a2b02cc2",
  "test_mode": true,
  "topic": "lead.created",
  "site": "019eca47-21a4-7935-8636-641e7370897b",
  "created_at": "2026-06-15T07:55:19Z",
  "arguments": {
    "test": true,
    "timestamp": 1781510118,
    "message": "This is a test webhook message from the admin panel."
  }
}

After receiving this notification, your app should call the API using its credentials to fetch the full data. This ensures that:

  • Sensitive data is never sent over the wire unnecessarily.
  • The App's Scopes are re-validated before data access.

Webhook Topics​

The following topics are currently supported:

TopicDescription
lead.createdTriggered when a new form submission is received.
order.createdTriggered when a new order is placed.
product.updatedTriggered when a product's details are changed.

Security and Verification​

HTTPS Requirement​

All webhook addresses must use the https:// protocol.

Signing (HMAC)​

Every webhook request is signed with your App Secret using HMAC-SHA384. You should verify this signature to ensure the request truly came from SitePack.

The signature is sent in the X-SitePack-Signature header.

Retries and Failures​

If your server returns anything other than a 2xx status code, SitePack will attempt to redeliver the webhook using an exponential backoff strategy for up to 24 hours.

Configuring Webhooks​

Add the webhooks array to your app.json:

{
  "webhooks": [
    {
      "topic": "lead.created",
      "address": "https://your-app.com/webhooks/leads"
    }
  ]
}

Next Steps​