External Events Webhook

Perkie gives you one URL to plug into any external tool — email platforms, form builders, booking systems, automation tools — and have customers earn points when external events happen. Someone subscribes to your newsletter in Mailchimp? Points. Fills out a contact form in Gravity Forms? Points. Books an appointment via Calendly? Points.

No plugin integration required. If your tool can send a POST request with a JSON body, Perkie can award points from it.

—

Where to find it

Turn the feature on at Tracksies > Settings > Features > enable External Events Webhook under the Perkie section. (It’s off by default — opt-in so stores that don’t need external integrations don’t run the endpoint at all.)

Then open Tracksies > Perkie > Integrations tab.

—

Setting it up

1. Copy the webhook URL

Top of the Integrations tab shows your unique webhook URL — something like:

https://yourstore.com/?perkie-webhook=AbCdEfGhIjKlMnOpQrStUvWxYz012345

Click Copy to put it on your clipboard. The URL is your store’s private key — don’t share it publicly. If it ever leaks, click Regenerate Key to invalidate it and get a fresh URL.

2. Configure your event types

Five built-in event types ship by default:

For each event, set the point value and toggle it on or off. Save.

3. Paste the URL into your external tool

Any tool that can send webhooks will have a URL field. Paste yours in. The payload your tool sends needs to include at minimum:

• The customer’s email address
• The event type (one of: subscribed, rewards_optin, form_completed, booking_made, custom)

Example JSON body:

{
  "email": "customer@example.com",
  "event": "subscribed"
}

Perkie’s endpoint accepts any reasonable shape — it looks for email-like fields (email, customer_email, user_email) and event-type-like fields (event, event_type, type) anywhere in the JSON.

4. Test it

Use curl, Postman, or your tool’s “test webhook” feature to send a sample event. Check the Recent Activity table at the bottom of the Integrations tab — your test should appear within a few seconds with a status like “Processed” or “Queued”.

Example curl command:

curl -X POST "https://yourstore.com/?perkie-webhook=YOUR_KEY" 
  -H "Content-Type: application/json" 
  -d '{"email":"test@example.com","event":"subscribed"}'

—

What happens when an event arrives

Perkie checks the email against your customer database:

If the email matches an existing customer — points are awarded immediately. Their balance goes up, they see the new total on their My Account page, and the standard Points Earned email fires (if enabled).

If the email doesn’t match any customer yet — the event is queued. The person isn’t a customer of yours right now, but they might be tomorrow. If they create an account within the expiry window (default 30 days, configurable up to 365), the queued event automatically fires when their account is created. They get their points on day one.

If the event is rewards_optin — Perkie enrols the customer in the rewards program even if they hadn’t previously been participating. Useful for programs using opt-in mode.

—

Why the queue matters

The queue is what makes this useful for stores that aren’t yet sure who their customers will be.

Say you run a newsletter in Mailchimp with 500 subscribers. Only 100 of them have ordered from you. When you turn on Perkie and connect the webhook for newsletter signups, the 100 existing customers get their points immediately for past subscriptions (if your tool re-fires events for existing contacts).

The other 400? They’re in the Perkie queue. If any of them create an account in the next 30 days, their newsletter-signup points are ready and waiting — they get a friendly welcome with a balance already on day one.

It’s a simple mechanic that turns “we have your email address” into a latent rewards relationship, ready to activate when they decide to buy.

—

Security

Every request is checked against several layers:

• Key validation — the perkie-webhook= parameter must exactly match your stored key. Invalid keys return 401 and are logged.
• Rate limiting — max 100 requests per minute per IP address. Exceeded requests return 429 with a “Retry-After: 60” header.
• Duplicate detection — if the same email + event type arrives twice within a short window (10 minutes), the second one is marked “Duplicate” and ignored. Prevents accidental double-awards when a tool retries on timeout.
• HTTPS recommended — the admin tab warns you if your site isn’t running on HTTPS. Your webhook key is in the URL, so over plain HTTP it’s visible to anyone watching the traffic.

Rotate the key whenever you change tools or suspect compromise. The Regenerate Key button instantly invalidates the old URL and gives you a fresh one.

—

Recent Activity log

Bottom of the Integrations tab shows the last 20 events with status indicators:

• Processed — points awarded to an existing customer
• Queued — event saved for a future account
• Duplicate — identical event received within the dedup window
• Rate limited — IP sent too many requests
• Error — something went wrong (check the Perkie debug log for details)
• Disabled — the event type arrived but is currently turned off in settings
• Not enrolled — customer exists but isn’t enrolled in the rewards program (only in opt-in mode)

If a webhook says it fired but points don’t appear, the Recent Activity log is the first place to look.

—

Debug logging

Enable Tracksies > Settings > Debug with the Perkie plugin key turned on. Every webhook request is logged in full under wp-content/uploads/tracksies-logs/perkie.log, prefixed with [webhook]. You’ll see the inbound URL, the parsed email, the parsed event type, the matched customer (if any), and the final outcome.

—

Tips

Start with one integration. Perkie will happily ingest hundreds of events per minute, but it’s much easier to debug when you start with one tool, watch the Recent Activity log for a week, and then add the next tool.

Use rewards_optin for explicit enrolment. If you’re running an opt-in-mode rewards program (not automatic enrolment), the rewards_optin event is how external tools ask Perkie to enrol a customer. Useful for “tick this box to join our rewards” forms in external tools.

Set sensible point values. 100 points for a newsletter subscription sounds generous — but remember it’s a small percentage of what they’ll earn from a single order. Match your earning rate so the webhook events feel proportional.

Queue expiry — 30 days is a good default. If you shorten it, you miss converting people who take a while to decide. If you lengthen it past ~90 days, you start accumulating stale queue entries for people who never convert. 30 covers most retail buying cycles without memory bloat.