How webhooks work
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
Section titled “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. |
| 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. |
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
Section titled “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.
A Custom webhook renders each Key / Value row as a Handlebars 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.
Templates are checked as you type (Invalid template: … disables Save) and again on save.
Product feed
Section titled “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.
Authentication
Section titled “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
Section titled “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
Section titled “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
Section titled “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
Section titled “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.
The URLs produced by Test Webhook have no workflow behind them, so calling them records nothing.
What the card shows
Section titled “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
Section titled “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.