Webhooks
Send your store's events to your own systems the moment they happen. Choosing events, testing an endpoint, signing secrets, retries and what to do when deliveries fail.
A webhook is a message Leal sends to a web address of yours whenever something happens in your store: a customer joins, a stamp is added, a reward is redeemed. Your system receives it within seconds and can do what it likes with it. Webhooks are for developers or tools that can receive them. If you just want to connect two apps, Zapier, Make or Pabbly Connect are easier.
You manage webhooks on the Webhooks page in your settings menu. Adding an endpoint needs a Pro plan.
Add an endpoint#
- Open Webhooks and click Add endpoint.
- Enter the Endpoint URL: a public https address on your server. Leal sends it a POST request for each event.
- Give it a Name (optional), such as "CRM sync", so you can tell your endpoints apart.
- Under Events to send, choose All events or pick the events this endpoint needs.
- Leave Payload format under Advanced settings on Standard unless you have a reason to change it.
- Click Add endpoint.
- On the next page, click Send test event to check your server answers.
Events#
| Event | Label in Leal | Sent when |
|---|---|---|
customer.created |
Customer joined | A customer signs up, from a poster, the app, an import or the API. |
customer.updated |
Customer updated | A customer's name, email, phone, birthday, metadata or marketing and SMS consent changes. |
customer_card.created |
Card issued | A customer gets a loyalty card. Includes the Apple Wallet and Google Wallet links. |
stamp.earned |
Stamps earned | Stamps are added to a card, by a scan, the API, an adjustment, welcome stamps or a referral. |
stamp.removed |
Stamps removed | Stamps are taken off a card by an adjustment. |
reward.unlocked |
Reward unlocked | A customer now has enough stamps for a reward. Sent once per reward, when they cross the line. |
reward.redeemed |
Reward redeemed | A customer redeems a reward. |
referral.created |
Friend joined with invite | A customer joins with another customer's invite link. Nobody has earned anything yet. |
referral.rewarded |
Referral rewarded | The referred customer's card is stamped for their first visit, so both customers get their referral stamps. |
All events also includes any events Leal adds in future. Choose only the events you need if your server can't cope with surprises.
Redeeming a reward sends reward.redeemed, not stamp.removed, even though it uses up stamps.
Payload formats#
| Format | What your server receives | Use it when |
|---|---|---|
| Standard (recommended) | An envelope with the event's id, type and time, and the details under data. |
Almost always. |
| Flat | Only the details. The event name is in the Leal-Event header. |
A tool expects the bare object, as Zapier does. Works with a single event only. |
Checking requests really come from Leal#
Each endpoint has a Signing secret. Leal signs every request with it, using the Standard Webhooks scheme, and sends the signature in the webhook-signature header alongside webhook-id and webhook-timestamp. Your developer can check the signature so nobody can fake a request to your server. The webhooks guide has examples in Node, Python and Ruby.
If the secret leaks, click Rotate secret. The old secret stops working immediately, so update your server straight after.
Deliveries, retries and failures#
- Your server should answer with a 2xx status (such as 200) quickly. Anything else counts as a failure.
- Leal retries a failed delivery up to 10 times, waiting longer each time. The retries cover roughly four hours.
- The endpoint page shows the Last delivery: when it was Attempted, the Response and any Error.
- If nothing has been delivered successfully for three days, Leal switches the endpoint off and marks it Disabled. Fix your server, send a test event, then click Re-enable.
- Leal only sends to addresses on the public internet. An endpoint pointing at a private address is switched off and marked Blocked. Change the URL, then re-enable it.
- If your server answers
410 Gone, Leal deletes the endpoint. That's how Zapier tells Leal a Zap was removed.
The test event (webhook.test) is sent once, straight away, with no retries. It doesn't change the endpoint's delivery history.
Pausing and deleting#
- Pause stops events going to the endpoint until you click Resume. Events that happen while it's paused aren't sent later.
- Delete removes it. Leal stops sending straight away.
Endpoints labelled Zapier, Make or Pabbly Connect were created by those platforms. Manage them from the platform, not here. See Automation.
Gotchas#
- Events can arrive more than once. A retry sends the same event again with the same
webhook-id. Use it to ignore duplicates. - Events can arrive out of order. Use the timestamp, not the arrival order.
- Webhooks belong to one store. If you run several stores, add an endpoint in each.
- https only. Plain http addresses aren't accepted for live stores.
Best practices#
- Subscribe each endpoint to only the events it handles.
- Answer quickly and do the slow work afterwards, so deliveries don't time out.
- Always verify the signature.
- Send a test event whenever you change your server.
For full payload examples and the webhooks API, see the developer guide.
Still stuck?
Our team answers every message. Contact support