Webhooks
EasyCoupon sends a signed JSON message (HTTP POST) to your URL when a code is issued, a wheel is spun, a coupon is redeemed or an email is captured. Use it with Zapier, Make or your own system.
Adding an endpoint
- Under Settings, on the Integrations tab, in Webhooks, click Add endpoint.
- Enter the HTTPS URL and pick the Events you want.
- After saving, copy the Signing secret: value (
whsec_…) if your receiver checks signatures. Send test sends awebhook.testevent.
You can add up to 5 endpoints. Only https:// addresses work, and none that point to a private network (private IP address). In Zapier paste the URL of a “Webhooks by Zapier → Catch Hook” trigger, in Make a “Custom webhook”.
Events
coupon.issued– a coupon code was given to a shopper.wheel.spun– a shopper spun a wheel (won or not).coupon.redeemed– a coupon was used.email.captured– a shopper left their email address.webhook.test– the test event sent with Send test.
We only send webhooks for things that happened on the server, never for signals from the shopper’s browser.
Message format
Every message comes in the same envelope; the data part differs per event (keys are snake_case). Example:
{
"id": "evt_6f1d2c9a0b7e4c3f8a1d5e2b9c0f4a7d",
"type": "coupon.issued",
"created_at": "2026-11-12T09:30:00.000Z",
"tenant_id": "…",
"data": {
"coupon_id": "…", "code": "WELCOME-L9LHGLVE",
"pool_id": "…", "pool_name": "Welcome 10%",
"discount_type": "percent", "discount_value": 10,
"expires_at": null, "sync_mode": "proxy", "sid": "…"
}
}
wheel.spun:wheel_pool_id,sid,won,segment,segment_label,prize_pool_id.coupon.redeemed:coupon_id,code,pool_id,pool_name,order_id,order_total,currency,email,source,sid.email.captured:email,verified(alwaysfalse: the shopper typed it),consent_at,consent_text,privacy_url,pool_id,pool_name,coupon_id,code,sid.
discount_type is percent, fixed or free_shipping; sync_mode is proxy or api.
What coupon.redeemed carries per shop
- Shoprenter proxy mode: when the code is applied in the cart; no order id, total or email.
- Shoprenter shop API mode: on the order success page, with the order id; no total or email.
- Shopify: from the order, with order id, total, currency and email (when Shopify provides it).
Verifying the signature
Signatures follow the Standard Webhooks spec. Every request carries three headers: webhook-id, webhook-timestamp (Unix seconds) and webhook-signature (v1,<base64>).
- Take the secret without the
whsec_prefix and decode it from base64: that is the key. - Compute HMAC-SHA256 over
webhook-id + "." + webhook-timestamp + "." + raw body(the body exactly as received, not re-serialized). - Its base64 must equal the part of
webhook-signatureafterv1,. Reject old timestamps (for example older than 5 minutes).
import crypto from 'node:crypto';
// secret: "whsec_…" from the admin; rawBody: the request body exactly as received
export function verify(secret, headers, rawBody) {
const id = headers['webhook-id'];
const ts = headers['webhook-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = crypto.createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64');
return headers['webhook-signature'].split(' ').some((part) => {
const sig = part.split(',')[1] ?? '';
return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
});
}
Rotate secret creates a new signing secret; your receiver must then use the new one.
Delivery and retries
- A 2xx response counts as delivered; your receiver has 10 seconds to answer.
- On failure there are 8 attempts in total, with growing pauses (1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours): about 2 days.
- If 50 deliveries in a row fail and the endpoint has been failing for at least 24 hours, it is switched off: Disabled after repeated failures.
- The delivery log is kept for 30 days under the endpoint (Delivered, Pending, Failed).
- The same event can arrive more than once: deduplicate by
webhook-id.