# Webhooks API overview

> What Releva sends to your webhook URL (payload, batches, authentication, retries), and the GET /webhooks/events endpoint your system calls to record webhook opens and clicks: auth, parameters, responses, errors and limits.

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](https://releva.ai/documentation/learn/webhooks/how-webhooks-work/).

## 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](https://releva.ai/documentation/guides/webhooks/send-data-in-your-receivers-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.

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

```plaintext
# 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](https://releva.ai/documentation/learn/webhooks/how-webhooks-work/#standard-and-custom).

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

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:

```plaintext
authorization: Bearer $RELEVA_ACCESS_TOKEN
```

The header wins if both are present. Find the token under **Settings › Shop & Integration**; see [Find your API keys](https://releva.ai/documentation/guides/shop-settings/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

| 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

```plaintext
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

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

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

* 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](https://releva.ai/documentation/learn/webhooks/how-webhooks-work/#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.

## 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](https://releva.ai/documentation/changelog/api/).

## Next steps

* [How webhooks work](https://releva.ai/documentation/learn/webhooks/how-webhooks-work/): Learn the webhook types, authentication, retries and the daily limit.
* [Create a webhook](https://releva.ai/documentation/guides/webhooks/create-a-webhook/): Add a webhook so a workflow can send it.
* [Send data in your receiver’s format](https://releva.ai/documentation/guides/webhooks/send-data-in-your-receivers-format/): Map the body to the fields your endpoint expects.
* [Events API overview](https://releva.ai/documentation/reference/events/overview/): Send events to Releva that can start a workflow.