# Cloudhooks

> Cloudhooks is a Shopify app that lets stores run custom JavaScript code when Shopify events happen — without hosting a webhook server. Write a hook, deploy in minutes. Cloudhooks handles webhook delivery, logging, retries, and Shopify API authentication automatically.

## How hooks work

A hook is a CommonJS module with the signature:

    module.exports = async function(payload, actions, context) {}

- `payload` — raw Shopify webhook data for the triggering event (order, customer, product, inventory level, fulfillment, refund, cart, checkout, draft order)
- `actions` — built-in functions for Shopify API calls, external HTTP requests, email, and PostgreSQL queries
- `context` — runtime info: `context.isTestMode` (boolean), `context.shopifyDomain` (string), `context.env` (environment variables object)

No `import` or `require` statements are allowed. All capabilities are provided through `actions` and `hookUtils`.

## Available actions

### Shopify API
- `actions.shopify.graphql(url, query)` — Shopify GraphQL Admin API. Supported versions: 2025-07, 2025-10, 2026-01, 2026-04. Use JSON query format. The query result is in the `data` property of the response.
- `actions.shopify.get(url)` — Shopify REST GET. URL starts with `/` (no domain). Content-Type and access key handled automatically.
- `actions.shopify.post(url, data)` — Shopify REST POST.
- `actions.shopify.put(url, data)` — Shopify REST PUT.
- `actions.shopify.delete(url)` — Shopify REST DELETE.
- `actions.shopify.tagOrder(orderId, tags)` — Add or remove tags on a Shopify order.
- `actions.shopify.tagCustomer(customerId, tags)` — Add or remove tags on a Shopify customer.

### External HTTP
- `actions.http.get(url, config?)` — GET request to any external API. Config is an optional Axios configuration object.
- `actions.http.post(url, data, config?)` — POST to an external endpoint.
- `actions.http.put(url, data, config?)` — PUT to an external endpoint.
- `actions.http.patch(url, data, config?)` — PATCH to an external endpoint.
- `actions.http.delete(url, config?)` — DELETE to an external endpoint.

### Email
- `actions.email.send({ from, to, subject, cc, body })` — Send email from a hook. Body can be HTML or plain text.

### PostgreSQL
- `actions.pg.query(connection, query, config?)` — Query a PostgreSQL database. Connection is a string or connection object.

### Utilities
- `hookUtils.crypto` — Node.js `crypto` package for HMAC, hashing, and cryptographic operations.

## Best practices
- Use `async/await` for all promises.
- Use `try/catch` for error handling.
- Use `console.log()` for debug output; `console.error()` for errors.
- Use `for...of` for async loops (not `forEach`).
- Always verify property existence before use.
- Use `context.isTestMode` to branch between test and live behaviour.
- Use `context.env` to access secrets — never hardcode credentials.
- Access payload directly (e.g. `payload.id`, not `payload.order.id`).

## Overview

- [Homepage](https://www.cloudhooks.dev/): Product overview, pricing, and reviews.
- [Help centre](https://www.cloudhooks.dev/help): Full documentation index.
- [Pricing explained](https://www.cloudhooks.dev/help-article/pricing-features-explained): Free tier (100 actions/month), $0.01/action up to 50k, $0.005 above that. No subscription.
- [App Store listing](https://apps.shopify.com/serverless-extensions): Shopify App Store install page.

## Getting started

- [What is Cloudhooks?](https://www.cloudhooks.dev/help-article/what-is-cloudhooks): Product introduction and core concepts.
- [What is a hook?](https://www.cloudhooks.dev/help-article/what-is-a-hook): Hook structure, the module.exports signature, and how hooks execute.
- [Installation](https://www.cloudhooks.dev/help-article/installation): How to install Cloudhooks from the Shopify App Store.
- [Creating your first hook](https://www.cloudhooks.dev/help-article/creating-your-first-hook): Step-by-step guide to writing and deploying a hook.
- [Trigger events](https://www.cloudhooks.dev/help-article/trigger-events): All supported Shopify webhook topics — orders, customers, products, inventory levels, fulfillments, refunds, carts, checkouts, and more.
- [Hook context](https://www.cloudhooks.dev/help-article/hook-context): The `context` variable — isTestMode, shopifyDomain, env.
- [Environment variables](https://www.cloudhooks.dev/help-article/environment-variables): Store API keys and config at store or hook level; access via `context.env`.
- [External triggers](https://www.cloudhooks.dev/help-article/external-triggers): Create HTTPS endpoints to receive events from outside Shopify — Stripe, ERPs, custom backends. Supports Bearer, API Key, Basic Auth, and HMAC authentication.
- [Testing your hook](https://www.cloudhooks.dev/help-article/testing-your-hook): Run hooks against sample or custom payloads in the cloud sandbox before going live.
- [Use development stores and test cards](https://www.cloudhooks.dev/help-article/use-development-stores-and-test-cards): Safe testing without real charges or customer emails.
- [Getting started section](https://www.cloudhooks.dev/help/getting-started): Documentation index for new users.

## Actions — Shopify API

- [shopify.graphql](https://www.cloudhooks.dev/help-article/action-shopify-graphql): Run Shopify GraphQL queries and mutations. Preferred method for Admin API interactions.
- [shopify.get](https://www.cloudhooks.dev/help-article/action-shopify-get): Shopify REST GET request.
- [shopify.post](https://www.cloudhooks.dev/help-article/action-shopify-post): Shopify REST POST request.
- [shopify.put](https://www.cloudhooks.dev/help-article/action-shopify-put): Shopify REST PUT request.
- [shopify.delete](https://www.cloudhooks.dev/help-article/action-shopify-delete): Shopify REST DELETE request.
- [shopify.tagOrder](https://www.cloudhooks.dev/help-article/action-shopify-tagorder): Add or remove tags on a Shopify order.
- [shopify.tagCustomer](https://www.cloudhooks.dev/help-article/action-shopify-tagcustomer): Add or remove tags on a Shopify customer.
- [Actions reference](https://www.cloudhooks.dev/help/actions): Full actions documentation index.

## Actions — External HTTP

- [http.get](https://www.cloudhooks.dev/help-article/action-http-get): GET request to any external API.
- [http.post](https://www.cloudhooks.dev/help-article/action-http-post): POST to an external endpoint with a request body.
- [http.put](https://www.cloudhooks.dev/help-article/action-http-put): PUT to an external endpoint.
- [http.patch](https://www.cloudhooks.dev/help-article/action-http-patch): PATCH to an external endpoint.
- [http.delete](https://www.cloudhooks.dev/help-article/action-http-delete): DELETE to an external endpoint.
- [Configure your HTTP request](https://www.cloudhooks.dev/help-article/configure-your-http-request): Set custom headers, authentication, timeouts, and proxy config via Axios config object.

## Actions — Email and database

- [email.send](https://www.cloudhooks.dev/help-article/action-email-send): Send email from a hook with from, to, subject, cc, and HTML or text body.
- [pg.query](https://www.cloudhooks.dev/help-article/action-pg-query): Query a PostgreSQL database directly from a hook.

## Patterns and best practices

- [Hook utilities (hookUtils)](https://www.cloudhooks.dev/help-article/hook-utilities): Available utilities — hookUtils.crypto (Node.js crypto module).
- [Await your actions](https://www.cloudhooks.dev/help-article/await-your-actions): How and when to await async actions in a hook.
- [Branching on run mode](https://www.cloudhooks.dev/help-article/branching-hook-code-based-on-run-mode): Use context.isTestMode to run different logic in test vs. live mode.
- [Use try/catch to handle errors](https://www.cloudhooks.dev/help-article/use-try-catch-to-handle-errors): Error handling patterns for production hooks.
- [Exit early from update hooks](https://www.cloudhooks.dev/help-article/exit-early-from-update-hooks): Return early to avoid unnecessary processing.
- [Debug with log entries](https://www.cloudhooks.dev/help-article/debug-with-log-entries): Use console.log and console.error to write to the execution log.
- [Use static endpoint URLs](https://www.cloudhooks.dev/help-article/use-static-endpoint-urls): Keep external trigger URLs stable across hook updates.
- [Best practices](https://www.cloudhooks.dev/help/best-practices): Full best practices documentation index.
- [Cloudhooks GPT prompting guide](https://www.cloudhooks.dev/help-article/cloudhooks-gpt-prompting-guide): How to prompt AI assistants to write Cloudhooks hook code effectively.

## Examples

- [Add subscriber to Mailerlite](https://www.cloudhooks.dev/help-article/example-add-subscriber-to-mailerlite): Sync a Shopify customer to a Mailerlite subscriber list on registration.
- [Email me when a refund is requested](https://www.cloudhooks.dev/help-article/example-email-me-when-a-refund-is-requested): Send an internal email notification when a Shopify refund is created.
- [Use cart attributes in your hook](https://www.cloudhooks.dev/help-article/example-how-to-use-cart-attributes-in-your-hook): Access and use custom cart attributes from the order payload.
- [Reminder to thank big spenders](https://www.cloudhooks.dev/help-article/example-reminder-to-thank-big-spenders): Trigger a follow-up action for high-value orders.
- [Send event to Google Analytics 4](https://www.cloudhooks.dev/help-article/example-send-event-to-google-analytics-4): Fire a GA4 Measurement Protocol event from a Shopify order hook.
- [Sync Shopify customer data to Zendesk](https://www.cloudhooks.dev/help-article/sync-shopify-customer-data-to-zendesk): Keep Zendesk customer records in sync from Shopify events.
- [Examples index](https://www.cloudhooks.dev/help/examples): Full examples documentation index.

## Use case guides

- [Connect Stripe to Shopify — subscription orders](https://www.cloudhooks.dev/articles/how-to-build-a-subscription-store-connecting-stripe-to-shopify-with-cloudhooks): Automatically create a Shopify order when a Stripe subscription payment succeeds.
- [Send personalised product emails with Brevo](https://www.cloudhooks.dev/articles/how-to-send-personalized-product-emails-connecting-shopify-brevo-and-cloudhooks): Trigger Brevo email templates based on Shopify order events.
- [Automate Shopify product creation with Zapier](https://www.cloudhooks.dev/articles/automating-shopify-product-creation-with-zapier-and-cloudhooks): Create Shopify products automatically from a Google Sheet via Zapier.
- [Automate Shopify product categorisation with AI](https://www.cloudhooks.dev/articles/how-to-use-ai-for-automatic-shopify-product-categorization): Assign Shopify product categories automatically using Product Classifier and Cloudhooks.
- [Sync Shopify customers to Zendesk](https://www.cloudhooks.dev/articles/automate-shopify-zendesk-customer-data-sync-a-step-by-step-guide-with-cloudhooks): Keep Zendesk customer records updated from Shopify events.
- [Update Google Sheets from Shopify sales events](https://www.cloudhooks.dev/articles/harness-cloudhooks-for-real-time-google-sheets-updates-from-sales-to-spreadsheets): Write Shopify order data to Google Sheets in real time.

## Key changelog entries

- [Shopify REST API deprecation notice](https://www.cloudhooks.dev/changelog/important-shopify-rest-admin-api-deprecation-notice): Shopify's migration from REST to GraphQL Admin API — what Cloudhooks users need to know and do.
- [External triggers](https://www.cloudhooks.dev/changelog/connect-your-systems-to-shopify-with-external-triggers): Announcement of HTTPS endpoint triggers for receiving events from outside Shopify.
- [Environment variables](https://www.cloudhooks.dev/changelog/introducing-environment-variables-secure-reusable-hooks-across-multiple-stores): Store secrets securely; reuse hooks across multiple stores.
- [Failed hook notifications](https://www.cloudhooks.dev/changelog/stay-informed-introducing-failed-hook-notifications): Proactive alerts when a hook fails in production.
- [Product categorisation with Product Classifier](https://www.cloudhooks.dev/changelog/introducing-automated-product-categorization-with-product-classifier): Announcement of the Product Classifier integration for automatic Shopify categorisation.