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.
When to use it
Section titled “When to use it”- 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/webhookClickURLs 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.
What Releva sends (Standard webhooks)
Section titled “What Releva sends (Standard webhooks)”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 endpointcurl -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.
Record an open or a click
Section titled “Record an open or a click”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.
Authentication
Section titled “Authentication”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_TOKENThe 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. |
Query parameters
Section titled “Query parameters”| 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. |
Request
Section titled “Request”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'Response
Section titled “Response”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
statusother thanOpenorClick(for exampleopenin lower case); - an empty or non-numeric
campaignId. The URLs produced by Test Webhook have an emptycampaignId, so calling them records nothing.
Errors
Section titled “Errors”| 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.
Limits
Section titled “Limits”- 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://andwww.addresses; use HTTPS so the payload and any secret travel encrypted.
Versioning
Section titled “Versioning”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.