Leal webhooks

Set up in three steps

1. 1. Add an endpoint

   In Leal, open Webhooks in your account settings, paste your URL and pick the events you want. The URL has to be public and use https. Choose All events to get everything, including events we add later, at one URL.

   Or do the same with the API, using an API token and the id of your store. List the events you want, or pass ["*"] for every event.

   curl -X POST https://app.tryleal.dev/api/v1/accounts/1/webhook_subscriptions \
     -H "Authorization: Bearer $LEAL_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"events": ["reward.unlocked", "reward.redeemed"], "target_url": "https://example.com/hooks/leal"}'

2. 2. Keep the secret

   Every endpoint has a signing secret starting whsec_. It is on the endpoint's page in Leal, and in the API response. Store it with your other credentials: you need it to check that a request really came from Leal. You can replace it at any time with Rotate secret.

   {
     "id": 12,
     "account_id": 1,
     "events": [
       "reward.unlocked",
       "reward.redeemed"
     ],
     "event": null,
     "target_url": "https://example.com/hooks/leal",
     "description": null,
     "payload_format": "envelope",
     "enabled": true,
     "disabled_at": null,
     "disabled_reason": null,
     "last_delivery_at": null,
     "last_delivery_status": null,
     "last_delivery_error": null,
     "created_at": "2026-09-28T09:00:00.000Z",
     "updated_at": "2026-09-28T09:00:00.000Z",
     "secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD"
   }

3. 3. Send yourself a test event

   Click Send test event on the endpoint's page, or call the test endpoint. Leal posts a signed webhook.test event to your URL straight away and tells you what came back, so you can check your endpoint and your signature code without waiting for a customer.

   curl -X POST https://app.tryleal.dev/api/v1/accounts/1/webhook_subscriptions/12/test \
     -H "Authorization: Bearer $LEAL_API_TOKEN"

   {
     "delivered": true,
     "status": 204,
     "event_id": "evt_2kXv8Rr5mQ1nH7cT4pW9yZ3b",
     "error": null
   }

The request

Each event is a POST with a JSON body and these headers:

POST /hooks/leal HTTP/1.1
Content-Type: application/json
User-Agent: Leal-Webhooks/1.0 (+https://www.tryleal.dev/developers/webhooks)
Leal-Event: reward.unlocked
webhook-id: evt_7Qm2cT9xKpW4rB8nZs3fLd1a
webhook-timestamp: 1790599218
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

The body

The body is an envelope around the object the event is about:

id

Unique id of the event, starting evt_. The same on every retry, and the same as the webhook-id header. Use it to ignore duplicates.

type

The event, for example reward.unlocked.

timestamp

When the event happened, in ISO 8601 UTC.

account_id

The store the event belongs to.

data

The object the event is about. Its shape depends on the event, see below.

previous_attributes

customer.updated only: the old values of the fields that changed.

Flat payloads and Zapier

Subscriptions made by the Zapier integration use "payload_format": "flat", which sends the data object on its own so Zaps can map its fields directly. You can ask for it too when you create a subscription with a single event. The event name is still in the Leal-Event header and the request is still signed. A customer.created event in flat format looks like this:

{
  "id": 42,
  "account_id": 1,
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "[email protected]",
  "phone": "+353861234567",
  "birthday": "1990-12-10",
  "stamp_count": 0,
  "metadata": {
    "favourite_drink": "flat white"
  },
  "marketing_opted_out_at": null,
  "sms_opted_out_at": null,
  "external_references": [
    {
      "source": "square",
      "external_id": "SQ-CUST-9981",
      "metadata": {}
    }
  ],
  "created_at": "2026-09-28T09:15:02.311Z",
  "updated_at": "2026-09-28T09:15:02.311Z"
}

Test events carry {"message":"This is a test event from Leal.","webhook_subscription_id":12} as their data.

Verifying signatures

Anyone who knows your URL can post to it, so check the signature before you trust a request. Leal signs every delivery with the Standard Webhooks scheme, which has ready made libraries for most languages. By hand, it is three steps:

1. Join the webhook-id header, the webhook-timestamp header and the raw request body with full stops: id.timestamp.body.
2. Compute an HMAC SHA-256 of that string. The key is your secret without the whsec_ prefix, base64 decoded. Base64 encode the result.
3. webhook-signature is a space separated list of v1,<signature> values. Accept the request if one of them matches, using a constant time comparison, and reject it if the timestamp is more than five minutes from now.

Always verify the raw bytes you received. Parsing the JSON and serialising it again changes the body and the signature will not match.

Node.js

// npm install standardwebhooks express
import express from "express";
import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.LEAL_WEBHOOK_SECRET); // "whsec_..."
const app = express();

// Verify against the raw body: parsing and re-serialising the JSON breaks the signature.
app.post("/hooks/leal", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = webhook.verify(req.body.toString(), req.headers);
  } catch {
    return res.status(400).send("Invalid signature");
  }

  if (event.type === "reward.unlocked") {
    const { customer, reward } = event.data;
    console.log(`${customer.first_name} can now redeem ${reward.name}`);
  }

  res.sendStatus(204);
});

app.listen(3000);

Python

# pip install standardwebhooks flask
import os
from flask import Flask, abort, request
from standardwebhooks.webhooks import Webhook

webhook = Webhook(os.environ["LEAL_WEBHOOK_SECRET"])  # "whsec_..."
app = Flask(__name__)

@app.post("/hooks/leal")
def leal_webhook():
    try:
        event = webhook.verify(request.get_data(), request.headers)
    except Exception:
        abort(400)

    if event["type"] == "reward.unlocked":
        customer, reward = event["data"]["customer"], event["data"]["reward"]
        print(f"{customer['first_name']} can now redeem {reward['name']}")

    return "", 204

Ruby

# No gem needed. In a Rails controller:
class LealWebhooksController < ActionController::API
  def create
    return head :bad_request unless valid_signature?

    event = JSON.parse(request.raw_post)
    case event["type"]
    when "reward.unlocked"
      customer, reward = event["data"].values_at("customer", "reward")
      Rails.logger.info "#{customer["first_name"]} can now redeem #{reward["name"]}"
    end

    head :no_content
  end

  private

  def valid_signature?
    id = request.headers["webhook-id"]
    timestamp = request.headers["webhook-timestamp"].to_i
    return false if (Time.now.to_i - timestamp).abs > 300 # five minutes

    key = Base64.decode64(ENV.fetch("LEAL_WEBHOOK_SECRET").delete_prefix("whsec_"))
    expected = Base64.strict_encode64(
      OpenSSL::HMAC.digest("SHA256", key, "#{id}.#{timestamp}.#{request.raw_post}")
    )

    request.headers["webhook-signature"].to_s.split(" ").any? do |candidate|
      version, signature = candidate.split(",", 2)
      version == "v1" && ActiveSupport::SecurityUtils.secure_compare(signature.to_s, expected)
    end
  end
end

Responding, retries and failures

• Reply with any 2xx status within 10 seconds. Do slow work after you respond, in a queue.
• Anything else is retried: other status codes, timeouts, connection errors and redirects, which are not followed. Leal makes up to 10 attempts with growing gaps, over about four hours.
• A retry has the same webhook-id and body, so store the ids you have handled and skip repeats. Events can also arrive out of order: use timestamp or the balances in the payload rather than the order of arrival.
• Reply 410 Gone and Leal deletes the subscription.
• If no delivery to a subscription has succeeded for three days, Leal switches it off: enabled becomes false and disabled_reason is failing. Fix the endpoint, then click Re-enable on its page in Leal, or send PATCH with {"enabled":true}.
• The endpoint's page in Leal shows the last delivery, and so does the API: every subscription has last_delivery_at, last_delivery_status and last_delivery_error, so you can see what your endpoint last returned.