Webhooks

Receive HTTP POST payloads when Shopwaive events occur — webhook events, payload fields, delivery headers, and HMAC-SHA256 signature validation

Webhooks let your service receive an HTTP POST payload whenever selected events occur in Shopwaive. They are available for Shopify stores and Shopify headless sites.

Webhooks require organization owner status and developer access. Contact [e-mail] to enable developer access for your organization.

Creating a webhook

Webhooks are configured from the Shopwaive web interface or the REST API. In the web interface, open the avatar menu in the upper-right corner, go to the Webhooks settings section, and select Add webhook. Provide:

• Payload URL — the URL where you'd like to receive payloads

• Event types — the events to subscribe to (individual webhook actions cannot be subscribed to separately)

• Secret (optional, recommended) — a random string with high entropy, used to validate deliveries

• Active — enable the webhook immediately

Upon creation, Shopwaive sends a simple ping event to confirm the webhook is set up correctly. You can create up to 5 webhooks for each event on each installation target. By default, webhooks are not subscribed to any events. Payloads are capped at 25 MB. IPv6 is not currently supported.

Events

• available_balance — a customer's available balance changes. The action field carries the cause: created, adjusted, redeemed, deleted, refund, imported, rest_api, or expired.

• Order invoice_url created with credit applied, and orders placed with credit.

• Customer email sent from an action (campaign_sent or manually_sent).

available_balance payload

Field	Type	Description
action	string	The action performed
available_balance.pre	string	Balance prior to the event
available_balance.post	string	Balance after the event
transaction	string	Associated transaction amount
customer_email	string	Customer's email address
order_id	string	Present only when action is redeemed
organization	object	Present when the webhook target is an organization: id, url (required); platform, currency, contactEmail (optional)

Delivery headers

Header	Description
X-Shopwaive-Hook-ID	The unique identifier of the webhook
X-Shopwaive-Event	The name of the event that triggered the delivery
X-Shopwaive-Delivery	A GUID identifying the delivery
X-Shopwaive-Signature-256	HMAC-SHA256 hex digest of the request body, signed with the webhook secret
X-Shopwaive-Hook-Installation-Target-Type	The type of resource where the webhook was created
X-Shopwaive-Hook-Installation-Target-ID	The unique identifier of that resource

Validating deliveries

If you set a secret, validate each delivery before processing it:

1. Read the X-Shopwaive-Signature-256 header. Its value always starts with sha256=.

2. Compute an HMAC-SHA256 hex digest of the raw request body using your webhook secret.

3. Compare your digest to the header value with a constant-time comparison — never a plain == operator. Use crypto.timingSafeEqual (Node.js), secure_compare (Ruby), or crypto.subtle.verify() (Web Crypto API).

Test vector for verifying your implementation — secret It's a Secret to Everybody, payload Hello, World!:

X-Shopwaive-Signature-256: sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17