Skip to content

Area: Developers

Webhooks API overview

Webhooks have two API surfaces:

Direction What Where
Releva → you A workflow step calls your URL with the profiles that reached it Your endpoint, configured under Marketing Channels › Webhooks
You → Releva GET /webhooks/events{/accessToken} records a webhook open or click for a profile https://releva.ai/api/v0

There is no public API to create, edit, test or delete webhooks; that is done in the admin. For the concepts, read How webhooks work.

  • Receive data: build an HTTPS endpoint that accepts the payload below (a Standard webhook), or configure a Custom webhook to match an existing API; see Send data in your receiver’s format.
  • Record opens and clicks: call the webhookOpen / webhookClick URLs from the payload when your system shows the message or the person clicks it. That is all the tracking endpoint is for; you normally never build its URL yourself.

This section is derived from Releva’s sender code and its unit tests; no request was observed on the wire while writing it.

A Standard webhook sends one POST per batch of up to 20 profiles that reached the workflow step. The request has content-type: application/json and, only when an Auth Secret is selected on the webhook, authorization: Bearer <secret value>. Without a secret there is no Authorization header.

# Equivalent of what Releva sends to your endpoint
curl -X POST 'https://hooks.demo-store.example.com/releva' \
-H 'content-type: application/json' \
-H "authorization: Bearer $YOUR_SECRET" \
-d '{
"source": {
"campaign": { "id": 9002, "name": "Win back customers", "tags": [{ "name": "retention" }] },
"segment": { "id": 9003, "name": "Bought in the last 30 days" },
"segmentRunId": "demo-run-0001",
"flowStepId": "demo-step-0001",
"batchNumber": 0
},
"profiles": [
{
"firstName": "Maria",
"lastName": "Example",
"email": "maria@example.com",
"phoneNumber": "+359888000000",
"profileId": "profile/15/DEMO-CUSTOMER-1001",
"tags": ["vip"],
"subscriptions": ["newsletter"],
"registeredAt": "2026-09-15T00:20:21.000Z",
"subscribedAt": null,
"custom": { "string": [{ "key": "favouriteColour", "values": ["blue"] }], "numeric": [], "date": [] },
"webhookOpen": "https://releva.ai/api/v0/webhooks/events/<accessToken>?userId=DEMO-CUSTOMER-1001&webhookId=9001&source=webhook&campaignId=9002&segmentId=9003&segmentRunId=demo-run-0001&status=Open&flowStepId=demo-step-0001",
"webhookClick": "https://releva.ai/api/v0/webhooks/events/<accessToken>?userId=DEMO-CUSTOMER-1001&webhookId=9001&source=webhook&campaignId=9002&segmentId=9003&segmentRunId=demo-run-0001&status=Click&flowStepId=demo-step-0001"
}
],
"triggerEvent": null
}'
Field Type Meaning
source.campaign object or null The workflow: id, name, tags (array of { "name" }). null for a Test Webhook send.
source.segment object or null The workflow’s segment: id, name. null when the workflow has none or for a test send.
source.segmentRunId string or null One execution of the workflow: the cohort that entered it.
source.flowStepId string or null The workflow step that sent the webhook.
source.batchNumber integer Zero-based batch number within this run and step.
profiles[] array Up to 20 profiles per request.
profiles[].firstName, lastName, email, phoneNumber string or null Empty values are sent as null.
profiles[].profileId string profile/<domainId>/<your customer id>.
profiles[].tags, subscriptions array of string
profiles[].registeredAt, subscribedAt ISO-8601 string or null
profiles[].custom object string, numeric and date lists of { key, values }.
profiles[].webhookOpen, webhookClick URL Call with GET to record an open or a click. See below.
profiles[].products, product array, object Only when a Product feed is selected on the webhook: up to 5 products and the first of them.
triggerEvent object or null The event that started a triggered workflow: action, actionClass, tags, custom, timestamp. null otherwise.

Your response:

  • Any 2xx status means delivered. The status and body are stored with the profile’s Webhook Delivered event.
  • Any other status, or a connection error, is retried up to 10 times with exponential back-off. After the last attempt the profiles in that request are recorded as bounced.

A Custom webhook does not use this body. It sends one request per profile with the method, format, headers, URL parameters and body you map in the admin; see How webhooks work.

GET /api/v0/webhooks/events GET /api/v0/webhooks/events/{accessToken}

Writes a webhookOpen or webhookClick event on the profile and attributes the profile to the workflow and step, so later purchases count as assisted by that workflow. The webhookOpen / webhookClick URLs in the payload are complete: call them as they are.

The endpoint uses the shop’s access token (the public key your website uses), not the secret key. Send it either as the last path segment, which is what the generated URLs do, or as a bearer header:

authorization: Bearer $RELEVA_ACCESS_TOKEN

The header wins if both are present. Find the token under Settings › Shop & Integration; see Find your API keys. The endpoint also works while the shop is disabled.

Authentication failures answer 400, not 401:

Problem Message
No header and no path token Authorization header is missing, and accessToken url parameters is also missing. At least one of them is required.
Header is not Bearer <token> Authorization header is malformed. It should look like `Bearer <string>`.
Token is not a UUID The access token you provided is invalid.
No shop has this token (including the secret key) Domain with the provided access token cannot be found.
Name Required Meaning
userId yes Your customer id for the profile (the part after profile/<domainId>/ in profileId).
webhookId yes Id of the webhook. Not checked to exist.
source yes Must be webhook.
campaignId yes Numeric id of the workflow.
segmentId yes Id of the workflow’s segment. May be empty.
segmentRunId yes The run id from source.segmentRunId. May be empty.
status yes Open records an open, Click records a click. Case-sensitive.
flowStepId no The step id from source.flowStepId, used for step attribution.
email no Validated when present, then ignored.
curl -sS -i "https://releva.ai/api/v0/webhooks/events?userId=DEMO-CUSTOMER-1001&webhookId=9001&source=webhook&campaignId=9002&segmentId=9003&segmentRunId=demo-run-0001&flowStepId=demo-step-0001&status=Click" \
-H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \
-H 'content-type: application/json'

202 Accepted with an empty body. The event is written asynchronously, usually within a second. Every call writes another event; there is no deduplication.

A 202 means the parameters were valid, not that an event was recorded. Two cases are accepted and then dropped:

  • a status other than Open or Click (for example open in lower case);
  • an empty or non-numeric campaignId. The URLs produced by Test Webhook have an empty campaignId, so calling them records nothing.
Status Message When
400 The 'userId' field is required. The 'source' field is required. The 'campaignId' field is required. The 'segmentId' field is required. The 'segmentRunId' field is required. The 'status' field is required. The 'webhookId' field is required. Required parameters missing. Messages for several fields are joined with a space.
400 The 'source' field value 'webhook' does not match any of the allowed values. source is not webhook. The quoted value is the allowed one.
400 The 'email' field must be a valid e-mail. email is present but not an address.
400 The 'userId' field must be a string. A parameter was repeated in the query string.
400 the four authentication messages above
400 We do not support non-HTTPS requests. Plain HTTP.
404 HTML Cannot POST /api/v0/webhooks/events/… Any method other than GET.

Errors have one shape, { "message": "…" }, except the 404, which is an HTML page.

  • No rate limit on the tracking endpoint. Call it once per real open or click.
  • Outbound: 20 profiles per Standard request; 10 retries per request; the shop’s Max Webhooks Per Day (1 to 10, default 3) per profile, except in triggered workflows, see The daily limit.
  • The tracking endpoint accepts HTTPS only. For the outbound side, the webhook form accepts http://, https:// and www. addresses; use HTTPS so the payload and any secret travel encrypted.

The tracking endpoint is under /api/v0. Fields have been added to the outbound payload without a version change (profileId, source.campaign.tags, triggerEvent.tags, products and product were added this way). Parse the payload leniently and ignore keys you do not know. Changes are listed in the API changelog.