Working With Webhooks

A webhook sends an HTTP POST request to a URL you specify whenever a defined event occurs. The payload includes structured JSON data describing what changed and the related entity.

Common use cases:

• Trigger order fulfillment or send confirmation emails when an order is placed.
• Sync product or stock updates to third-party systems.
• Send order confirmation emails.
• Rebuilding a static website when content has changed.
• Purge frontend cache for products that are updated.
• Automate publishing workflows with Flows and scheduling.

1. Go to Settings → Webhooks in the Crystallize app.
2. Click Add Webhook.
3. Enter the target URL where the webhook should be sent.
4. Choose which events should trigger it (for example, Order Created, Item Updated, Flow State Changed).
5. Optionally, add headers for authentication or custom integration logic.
6. Save and test your webhook.

When the selected event occurs, Crystallize sends a POST request to your endpoint with a JSON body like:

{
  "order": {
    "get": {
      "id": "68e4fe1da9733a66efd88673",
      "createdAt": "2025-10-07T11:48:45.000Z",
      "updatedAt": "2025-10-07T11:48:45.000Z",
      "customer": {
        "identifier": "bard@crystallize.com",
        "firstName": "Bård",
        "lastName": "Farstad"
      },
      "cart": [
        {
          "name": "In Utero",
          "sku": "4958411",
          "quantity": 1,
          "price": {
            "currency": "EUR",
            "gross": 35,
            "net": 28
          }
        },
        {
          "name": "The Best Of The Doors",
          "sku": "3795082",
          "quantity": 1,
          "price": {
            "currency": "EUR",
            "gross": 10.1125,
            "net": 8.09
          }
        }
      ],
      "total": {
        "currency": "EUR",
        "gross": 45.1125,
        "net": 36.09
      },
      "pipelines": null
    }
  }
}

{
  "order": {
    "get": {
      "id": "68e4fe1da9733a66efd88673",
      "createdAt": "2025-10-07T11:48:45.000Z",
      "updatedAt": "2025-10-07T11:48:45.000Z",
      "customer": {
        "identifier": "bard@crystallize.com",
        "firstName": "Bård",
        "lastName": "Farstad"
      },
      "cart": [
        {
          "name": "In Utero",
          "sku": "4958411",
          "quantity": 1,
          "price": {
            "currency": "EUR",
            "gross": 35,
            "net": 28
          }
        },
        {
          "name": "The Best Of The Doors",
          "sku": "3795082",
          "quantity": 1,
          "price": {
            "currency": "EUR",
            "gross": 10.1125,
            "net": 8.09
          }
        }
      ],
      "total": {
        "currency": "EUR",
        "gross": 45.1125,
        "net": 36.09
      },
      "pipelines": null
    }
  }
}

For added security, all webhook requests sent from Crystallize are signed. This allows you to confirm that the request genuinely comes from your Crystallize tenant and hasn’t been tampered with.

It’s your responsibility to verify this signature in your receiving endpoint before processing the event.

Each webhook request includes a x-crystallize-signature header containing the HMAC signature of the request body, generated using your tenant’s webhook secret and the SHA-256 algorithm.

When developing or testing your webhook implementation, you can use temporary endpoints to inspect and debug webhook calls before deploying to production.

• Webhook.site lets you instantly receive and inspect webhook requests in your browser. It’s ideal for debugging and understanding the payload structure sent from Crystallize.
• ngrok creates a secure tunnel to your local server, allowing Crystallize to send webhooks directly to your development environment. It’s perfect for end-to-end testing and local iteration.

These tools help ensure your webhook logic works correctly before you connect it to a live system.