Inbound Webhooks

📥 Inbound Webhooks

Receive events from external platforms and award seeds to your customers automatically. Inbound webhooks let you connect any third-party tool — quiz apps, forms, review platforms, Zapier, Make, and more — to your LoyaltyTree loyalty program.

How It Works

The inbound webhook system uses a Sources & Codes model:

1. Create a Source — A source represents an external platform or tool (e.g. "Typeform", "Zapier", "My Quiz App"). Each source gets a unique webhook URL and a secret key for security.
2. Add Codes to the Source — Each code defines a specific action that awards seeds (e.g. "quiz_completed", "form_submitted", "birthday_claimed"). You set how many seeds each code awards, with optional limits.
3. Send POST requests — Your external platform sends a POST request to the webhook URL with the code and customer info. LoyaltyTree finds or creates the customer and awards the seeds automatically.

Getting Started

Step 1: Create a Webhook Source

Navigate to Stores → [Your Store] → Integrations → Inbound Webhooks. Click + Add Source and give it a name that describes the external platform (e.g. "Typeform Quizzes" or "Zapier Automation").

When the source is created, you'll receive:

• Webhook URL — The endpoint your external platform will send requests to
• Webhook Secret — A secret key for signing requests (recommended for security)

Step 2: Add Codes

Each code represents a specific action you want to reward. Click + Add Code on your source to create one.

Field	Required	Description
Code	Yes	The exact value sent in the webhook payload (e.g. quiz_completed). This must match what your external platform sends.
Display Name	Yes	A human-friendly name shown in the admin dashboard and transaction history (e.g. "Quiz Completed").
Description	No	An optional note for your team about when this code is used.
Seeds Amount	Yes	How many seeds to award each time this code is triggered. Defaults to 1.
Max Seeds/Customer	No	The maximum total seeds a single customer can earn from this code. Leave empty for unlimited. Once a customer reaches this limit, further webhook calls for them will return success but award 0 seeds.
Cooldown (hours)	No	Minimum hours between awards for the same customer on this code. Prevents abuse by rate-limiting how often a customer can earn seeds. Leave empty for no cooldown.
Enabled	—	Toggle to enable or disable this code without deleting it. Disabled codes return a 403 error.

Codes & Limits Explained

Codes and their limits work together to give you precise control over how seeds are awarded:

Seeds Amount

Each code has a fixed seed amount. Every time the webhook is triggered with that code, the customer receives exactly that many seeds. For example, if you set "quiz_completed" to 5 seeds, every qualifying webhook call awards 5 seeds.

Max Seeds Per Customer

This sets a lifetime cap per customer per code. It's the total seeds that customer can earn from this specific code, not the number of times they can trigger it.

Cooldown (Hours)

Sets a minimum wait time between seed awards for the same customer on the same code. The cooldown timer starts from the last successful award.

Request Format

Send a POST request to your webhook URL with the following JSON body:

{
  "code": "your_code_here",
  "customer": {
    "email": "customer@example.com",
    "shopify_customer_id": "12345",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "metadata": {
    "quiz_score": 95,
    "source_page": "spring-quiz"
  }
}

* At least one of email or shopify_customer_id is required. Email is required when the customer doesn't already exist in LoyaltyTree.

HMAC Signature Verification (Recommended)

To verify that requests are genuinely coming from your platform (and not from someone who found your webhook URL), sign your requests using HMAC-SHA256.

Supported signature headers (LoyaltyTree checks all of these):

• X-Webhook-Signature
• X-Hub-Signature-256
• X-Signature

The signature value can be either the raw hex hash or prefixed with sha256= (both formats are accepted).

Alternative: Plain Token Authentication

If HMAC signing is not possible in your platform, you can pass your webhook secret as a plain token in the X-Token header. LoyaltyTree will compare it directly to your secret.

Example: Signing with Node.js

const crypto = require('crypto');

const payload = JSON.stringify({
  code: 'quiz_completed',
  customer: { email: 'jane@example.com' }
});
const signature = crypto
  .createHmac('sha256', 'your_webhook_secret')
  .update(payload)
  .digest('hex');
fetch('https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Webhook-Signature': signature
  },
  body: payload
});

Example: Signing with Python

import hmac, hashlib, json, requests

payload = json.dumps({
    "code": "quiz_completed",
    "customer": {"email": "jane@example.com"}
})
signature = hmac.new(
    b'your_webhook_secret',
    payload.encode('utf-8'),
    hashlib.sha256
).hexdigest()
requests.post(
    'https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID',
    headers={
        'Content-Type': 'application/json',
        'X-Webhook-Signature': signature
    },
    data=payload
)

Example: Using cURL (for testing)

curl -X POST https://loyaltytree.eco/webhooks/inbound/YOUR_SOURCE_ID \
  -H "Content-Type: application/json" \
  -H "X-Token: your_webhook_secret" \
  -d '{"code":"quiz_completed","customer":{"email":"jane@example.com"}}'

Response Format

Successful Response (200)

{
  "success": true,
  "seeds_awarded": 5,
  "transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customer_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef"
}

Successful but Limited (200)

When a cooldown or max seeds limit prevents the award, you still get a 200 response but with 0 seeds and an explanation:

{
  "success": true,
  "seeds_awarded": 0,
  "message": "Cooldown active. Try again in 18 hour(s)."
}

// or
{
  "success": true,
  "seeds_awarded": 0,
  "message": "Maximum seeds (15) already awarded for this code."
}

Error Responses

Use Case Examples

Connecting with Zapier

Zapier is one of the most popular ways to connect LoyaltyTree with hundreds of other apps. We are building a dedicated LoyaltyTree integration in the Zapier App Store, which will make setup even easier — look for it in the Zapier marketplace.

In the meantime, you can use Zapier's Webhooks by Zapier action to connect right now:

Connecting with Make (Integromat)

You can also use Make's HTTP / Make a request module to send webhooks to LoyaltyTree. Configure it the same way as Zapier — set the URL, add the JSON body with code and customer, and include your secret in the X-Token header.

Webhook Logs

Every inbound webhook call is logged and visible in the Inbound Webhooks section of your Integrations page. Logs show:

• Timestamp – When the webhook was received
• Source – Which source received it
• Status – Success or failure
• Details – Code used, seeds awarded, or error message
• Payload – The full request body (encrypted at rest)

Use the logs to verify your integration is working correctly and to troubleshoot any issues.

Troubleshooting

Security

• Each source gets a unique 64-character webhook secret, auto-generated and encrypted at rest
• Secrets can be regenerated at any time from the source settings (old secret stops working immediately)
• Request payloads are encrypted in the logs for privacy
• Signature verification uses timing-safe comparison to prevent timing attacks
• Sources and codes can be individually disabled without deleting them