Skip to content

Area: User guide

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.

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 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.

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.

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.

  • 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.

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.

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.

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.

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.

  • 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.