# 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](https://docs.getleal.com/integrations/automation) are easier.

You manage webhooks on the [Webhooks page](https://app.getleal.com/webhooks) in your settings menu. Adding an endpoint needs a Pro plan.

## Add an endpoint

1. Open **Webhooks** and click **Add endpoint**.
2. Enter the **Endpoint URL**: a public https address on your server. Leal sends it a POST request for each event.
3. Give it a **Name** (optional), such as "CRM sync", so you can tell your endpoints apart.
4. Under **Events to send**, choose **All events** or pick the events this endpoint needs.
5. Leave **Payload format** under **Advanced settings** on **Standard** unless you have a reason to change it.
6. Click **Add endpoint**.
7. 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](https://www.getleal.com/developers/webhooks) 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](https://docs.getleal.com/integrations/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](https://www.getleal.com/developers/webhooks).
