Skip to main content

Webhooks and Events

Webhooks​

Spaaza provides webhooks and event notifications which can post a standard JSON object to an external API endpoint. Webhooks are triggered by events in Spaaza and are commonly used to trigger another event in an external system - for example triggering an email to be sent when a customer receives a voucher.

Webhook format​

A webhook or event notification is a POST that Spaaza sends to a specific URL. The body of the POST is JSON that includes the object.

As with API endpoints, Spaaza may add fields containing new information to the JSON body of webhooks and event notifications. Spaaza will not remove any fields or change the field type of existing fields in webhooks without prior notification.

Configuring webhooks​

Some, but not all, webhooks can be configured as "triggers" in Console. Whenever the relevant event occurs we send a simple POST request to the URL. The body of the POST is JSON that includes the object.

We currently support triggers to the following services:

  • Standard webhook (a webhook of standard format sent as a POST to a URL of your choosing)
  • Klaviyo
  • Mailchimp (Mandrill)
  • Shopify

Other webhooks and notifications can be configured manually by our team so please get in touch if you would like us to set one up for you.

Verifying webhooks are from Spaaza​

So that you can verify that the POST originates from Spaaza we provide a signature in a request header (X-Spaaza-Hmac-SHA256).

The value of the header is a base64-encoded HMAC-SHA256 hash of the whole body of the request using a shared secret. Your code to handle the event would need to recreate the signature using the shared secret and compare it to the value in the header.

Signature verification is available for webhooks of type https. To use it, first create a webhook signature key using the add-webhook-signature endpoint, and then link it to your webhook configuration using the webhook_signature_id parameter when creating or updating a webhook with the add-webhook or alter-webhook endpoints.

How HMAC signature verification works​

  1. When a webhook is triggered, Spaaza computes an HMAC-SHA256 hash of the JSON payload using the webhook signature key as the secret.
  2. The hash is base64-encoded and sent as the X-Spaaza-Hmac-SHA256 header.
  3. When you receive the webhook, recompute the HMAC-SHA256 hash of the raw request body using the same shared secret key, base64-encode it, and compare it to the value in the header.

If the values match, the webhook is authentic and has not been tampered with in transit.

Available webhook events​

The following webhook events are available in Spaaza:

Event nameDescription
shopper.opted-inTriggered when a user opts in to the loyalty programme
shopper.opted-outTriggered when a user opts out of the loyalty programme
shopper.req-pwd-resetTriggered when a user requests a password reset
shopper.alteredTriggered when a user's profile is altered
shopper.notificationTriggered as a result of a send-notification request
shopper.joined-mail-listTriggered when a user joins the mailing list
shopper.transactionTriggered when a basket transaction is completed
shopper.loyalty-level-changedTriggered when a user's loyalty level changes
shopper.voucher-issuedTriggered when a voucher is issued to a user
shopper.voucher-unclaimedTriggered when a voucher is unclaimed
shopper.voucher-claimedTriggered when a voucher is claimed by a user
shopper.voucher-redeemedTriggered when a voucher is redeemed
shopper.voucher-deletedTriggered when a voucher is deleted
shopper.voucher-expiringTriggered when a voucher is approaching its expiry date
shopper.points-mutationTriggered when a points or wallet balance mutation occurs

Webhook management API endpoints​

The following API endpoints are available for managing webhook configurations and webhook signature keys:

Webhook configuration endpoints​

Webhook signature endpoints​