# How webhooks work

> What a webhook is in Releva, the difference between Standard and Custom webhooks, what Releva sends and when, how authentication, retries, the daily limit, skipping and open/click tracking work, and which numbers the card shows.

A **webhook** is a Marketing Channels message, like an email or an SMS, except that it goes to a URL you own instead of to a person. It holds the address, the request shape and a daily-limit rule. A **workflow** decides which profiles reach it and when; Releva then calls your URL with those profiles. Webhooks live under **Marketing Channels › Webhooks**.

Use a webhook to push Releva’s audiences and events into your own systems: a CRM, a loyalty platform, a data warehouse, an automation tool.

## Three parts: webhook, workflow, receiver

| Part         | Where                                     | What it does                                                                                                                                                                                         |
| ------------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Webhook**  | **Marketing Channels › Webhooks**         | The URL, the type (Standard or Custom), optional product feed and auth secret, and **If max webhooks per day is reached**. See [Create a webhook](https://releva.ai/documentation/guides/webhooks/create-a-webhook/). |
| **Workflow** | **Workflows**, or **Send** on the webhook | Picks the audience and the moment. A webhook can only be sent from a workflow (one off, continuous or triggered).                                                                                    |
| **Receiver** | Your endpoint                             | Accepts the request, answers with a 2xx status, and optionally calls the tracking URLs in the payload. See [Webhooks API overview](https://releva.ai/documentation/reference/webhooks/overview/).                     |

Saving a webhook makes no request. Only a launched workflow and **Test Webhook** call your URL. **Test Webhook** sends one real request for the profile you choose, so point it at a test endpoint.

## Standard and Custom

|                 | **Standard**                                                                     | **Custom**                                                                                                                          |
| --------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Requests        | One `POST` per batch of up to 20 profiles                                        | One request per profile                                                                                                             |
| Method and body | Always `POST`, always JSON, Releva’s fixed payload                               | **Request Method** (`GET`, `POST`, `PUT`, `DELETE`), **Format** (**JSON** or **URL-encoded form**), body and URL parameters you map |
| Headers         | `content-type: application/json`, plus `authorization` when a secret is selected | The same, plus your **Request Headers**                                                                                             |
| Best for        | Endpoints you build to read Releva’s format                                      | Third-party APIs with their own field names                                                                                         |

The Standard payload carries `source` (the workflow, its segment, the run and the step), `profiles` (name, email, phone, id, tags, subscriptions, custom fields, tracking URLs) and `triggerEvent` for triggered workflows. The full shape is in the [Webhooks API overview](https://releva.ai/documentation/reference/webhooks/overview/#what-releva-sends-standard-webhooks).

A Custom webhook renders each **Key** / **Value** row as a [Handlebars](https://handlebarsjs.com/) template per profile. **Request Body Parameters** become the JSON or form body (shown for `POST` and `PUT` only), **Request URL Parameters** are added to the query string, **Request Headers** are sent as headers. **Merge Tags** lists what you can use: profile fields such as `{{firstName}}`, `{{email}}`, `{{phoneNumber}}` and `{{profileId}}`, links, your custom profile fields as `{{custom.string.<field>}}`, dynamic coupons, `{{triggerEvent.…}}` in triggered workflows, `{{product.*}}` when a **Product feed** is selected, and `{{flowMessage.viberMessage.*}}` / `{{flowMessage.textMessage.*}}`, which carry the Viber or SMS message the same workflow already sent to that profile. See [Send data in your receiver’s format](https://releva.ai/documentation/guides/webhooks/send-data-in-your-receivers-format/).

Templates are checked as you type (**Invalid template: …** disables **Save**) and again on save.

## Product feed

Selecting a **Product feed** adds up to 5 recommended products per profile to what is sent: `products` and `product` (the first one) in the Standard payload, and `{{product.*}}` merge tags in a Custom webhook. Only feeds with the Marketing Channels scope are listed; see [How product feeds work](https://releva.ai/documentation/learn/product-feeds/how-product-feeds-work/).

## Authentication

Releva sends an `authorization: Bearer <value>` header only when an **Auth Secret** is selected on the webhook. The secret is a domain secret from **Settings › Shop & Integration**: a static value, or a token-refresh secret that Releva renews before each call. With no secret, there is no `Authorization` header at all. On a Custom webhook, a secret replaces any `Authorization` row in **Request Headers**.

If the secret has been revoked, the step sends nothing and is not retried. Other secret problems (missing secret, refresh failure) fail the step without contacting your endpoint, and the job is retried.

## Delivery and retries

* Any 2xx response counts as **Delivered**.
* Any other status or a network error is retried up to 10 times with exponential back-off. After that, the profiles in that request are recorded as **Bounces**.
* Releva writes one event per profile at each stage: **Webhook Sent** before the call, then **Webhook Delivered**, **Webhook Bounced** or skipped. These show on the profile timeline and feed the card counters.

## Skipping

A Custom row with **Skip sending if blank?** ticked skips a profile whose rendered value is empty, instead of sending an empty field. Skipped profiles count as **Skipped** on the card. In **Test Webhook**, a skipped profile shows a notice instead of a response.

## The daily limit

Each shop has a limit of webhooks per profile per day: **Max Webhooks Per Day** under **Settings › Messaging**, tab **Webhooks** (1 to 10, default 3). **If max webhooks per day is reached** on the webhook decides what happens to a profile already at the limit:

| Option           | What happens                                                                                                          |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Reschedule**   | The profile is retried on a later day, at least 24 hours later, up to **Max Reschedules** times (1 to 10, default 3). |
| **Send anyway**  | The limit is ignored.                                                                                                 |
| **Skip sending** | The profile is left out and counted as **Skipped**.                                                                   |

The limit is never applied in triggered workflows, and only when the webhook is set to **Reschedule** or **Skip sending**. The note under the setting says it applies to continuous campaigns and workflows; for all other uses the message is sent regardless of the limit.

## Tracking opens and clicks

Each profile in a Standard payload carries two ready-made URLs, `webhookOpen` and `webhookClick`. Call either with `GET` from your system, for example when your app shows the message or when the person clicks the link in it, and Releva records **Webhook Opened** or **Webhook Clicked** on the profile and attributes later purchases to the workflow and step. The URLs contain your public access token and need no extra authentication. Details and errors are in the [Webhooks API overview](https://releva.ai/documentation/reference/webhooks/overview/#record-an-open-or-a-click).

The URLs produced by **Test Webhook** have no workflow behind them, so calling them records nothing.

## What the card shows

The **Marketing Channels › Webhooks** list has one card per webhook with counters for the selected period (default 30 days):

| Counter         | Event                                                    | Share                |
| --------------- | -------------------------------------------------------- | -------------------- |
| **Sent**        | Webhook Sent                                             |                      |
| **Delivered**   | Webhook Delivered                                        | of Sent              |
| **Clicks**      | Webhook Clicked                                          | of Delivered         |
| **Conversions** |                                                          | of Clicks            |
| **Purchases**   |                                                          | of Conversions       |
| **Revenue**     |                                                          | in the shop currency |
| **Skipped**     | skipped by **Skip sending if blank?** or the daily limit | of Sent              |
| **Bounces**     | Webhook Bounced                                          |                      |

The people icon next to **Sent**, **Clicks**, **Conversions**, **Purchases** and **Bounces** opens **New segment** with a rule for that event, so you can target, for example, everyone whose request bounced. **Statistics** on the card opens the daily chart for the webhook.

## Managing webhooks

* Names are unique per shop: saving a duplicate answers **Webhook Name must be unique!**
* **Make a copy** on an existing webhook opens a new one named **Copy of \<name>**; it is not saved until you select **Save**.
* **Delete** asks for confirmation and cannot be undone. Remove the webhook from its workflows first.
* A webhook used in a non-triggered workflow cannot use `{{triggerEvent.…}}` tags.

## Next steps

* [Create a webhook](https://releva.ai/documentation/guides/webhooks/create-a-webhook/): Enter the URL that receives the data and save it for a workflow.
* [Send data in your receiver’s format](https://releva.ai/documentation/guides/webhooks/send-data-in-your-receivers-format/): Map body fields to merge tags so your endpoint gets exactly what it expects.
* [Webhooks API overview](https://releva.ai/documentation/reference/webhooks/overview/): See the payload Releva sends and record opens and clicks.
* [How consent works in Releva](https://releva.ai/documentation/learn/consent/how-consent-works-in-releva/): Learn why webhook campaigns reach only subscribed customers.