Appearance
Webhooks & integrations
Replora tells other systems about what happens on your sites through alerts (email, Slack and signed webhooks), puts replay links on HubSpot contacts, and picks up your Google Analytics events as session tags. This page is the technical side of each: payloads, signatures, permissions and limits.
Alerts
Where to find them: Websites › your site › Alerts › New alert. An alert watches every new session of the site and notifies its channels when one matches.
| Field | Values | Notes |
|---|---|---|
| Name | Up to 120 characters | Shown in every notification. |
| Tell me about | A JavaScript error · A failed request · A rage click · A dead click · A session tag · A visit to a page | The trigger. |
| Trigger value | Message contains (optional), Address contains (optional), tag name and Value (optional), Address contains | Up to 500 characters (tag names up to 64). Required for page visits. |
| Email to | Up to 10 addresses, separated by commas | |
| Slack incoming webhook | https://hooks.slack.com/… | Must be a Slack incoming webhook address. |
| Webhook | https://…, up to 500 characters | "A JSON POST, signed with the header X-Replora-Signature." |
| How often | At most once every 5 minutes, 15 minutes, hour (default), 6 hours or day | The API accepts 1–10 080 minutes. |
| On / Off | Turned off, the alert records and sends nothing. |
At least one channel is required. Test sends a test notification to every channel at once (at most 10 tests a minute) and shows which channels failed.
How notifications are grouped: each session counts once per alert. The first match is sent at once; matches during the quiet time are collected and sent together when it ends (one notification about the latest match, "and 4 more sessions"). A scheduled command (alerts:digest, every minute) sends those.
On SaaS installations the number of alerts per account is a plan limit (alerts.count).
Email and Slack
The email and the Slack message say which alert fired on which site, what matched and how many other sessions matched, with a link to the replay starting just before the moment it happened. In Slack the text from visitors' pages stays plain text (no @channel pings, no disguised links).
Webhooks
A webhook alert sends an HTTP POST to your URL:
http
POST /hooks/replora HTTP/1.1
Content-Type: application/json
User-Agent: Replora-Alerts/1.0
X-Replora-Signature: sha256=5c3f0e…
{
"event": "alert.triggered",
"alert": { "id": 4, "name": "Checkout errors" },
"site": { "id": 1, "name": "Demo Plant Shop" },
"session": "1f0c2b9e-7a4d-4c1e-9d55-0f3a8e7b6c21",
"detail": "TypeError: Cannot read properties of undefined (reading 'total')",
"at": "2026-11-20T10:12:04+00:00",
"more": 3,
"replay_url": "https://replora.example.com/sites/1/sessions/1f0c2b9e-7a4d-4c1e-9d55-0f3a8e7b6c21?t=1795169524000"
}| Field | Meaning |
|---|---|
event | alert.triggered, or alert.test for the Test button (the session is then 00000000-0000-4000-8000-000000000000). |
alert | The alert's id and name. |
site | The website's id and name. |
session | The matching session's id (UUID). |
detail | What matched, in one line: the error message, METHOD URL → status of a failed request, the clicked element's label, the tag, or the page. |
at | When it happened (ISO 8601, UTC). |
more | Other sessions that matched since the last notification. |
replay_url | The replay in the dashboard, starting just before the match (?t= in ms since epoch). |
Delivery rules:
- Answer with any
2xxstatus within 5 seconds. Redirects are not followed. - Each notification is sent once. A failure (timeout, other status) is kept on the alert as
last_error(shown in the dashboard and inGET /sites/{site}/alerts) and doesn't stop the other channels. - Webhook URLs must use
httpsand resolve to public addresses only. Private and local addresses (localhost,10.x,192.168.x…) are allowed only whereREPLORA_ALERTS_PRIVATE_WEBHOOKSallows them; by default only in the Single user edition, never in SaaS. The checked address is the one called (no DNS rebinding).
Verifying the signature
Each alert has its own secret, webhook_secret in the API (GET /sites/{site}/alerts/{alert}). The header is sha256= followed by the hex HMAC-SHA256 of the raw request body with that secret. Compute it over the bytes you received, before parsing the JSON, and compare in constant time.
PHP
php
<?php
$secret = getenv('REPLORA_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_REPLORA_SIGNATURE'] ?? '';
$expected = 'sha256='.hash_hmac('sha256', $body, $secret);
if (! hash_equals($expected, $header)) {
http_response_code(401);
exit;
}
$alert = json_decode($body, true);
// … create a ticket, page someone, store $alert['replay_url'] …
http_response_code(204);In Laravel: $request->getContent() for the body and $request->header('X-Replora-Signature').
Node (Express)
js
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/hooks/replora', express.raw({ type: 'application/json' }), (req, res) => {
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.REPLORA_WEBHOOK_SECRET).update(req.body).digest('hex');
const received = req.get('X-Replora-Signature') ?? '';
const ok = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!ok) return res.sendStatus(401);
const alert = JSON.parse(req.body.toString('utf8'));
console.log(alert.event, alert.detail, alert.replay_url);
res.sendStatus(204);
});
app.listen(3000);Use the raw body
Re-encoding parsed JSON changes spaces and escaping, and the signature no longer matches. Replora sends the JSON with unescaped slashes and Unicode.
Manage alerts through the API
sh
curl -X POST https://replora.example.com/api/v1/sites/1/alerts \
-H "Authorization: Bearer $REPLORA_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"name":"Checkout errors","trigger":{"type":"error","value":"checkout"},"channels":{"webhook":"https://ops.example.com/hooks/replora"},"cooldown_minutes":60}'The answer holds webhook_secret. See the Alerts API.
HubSpot
When a visitor is identified by email, their HubSpot contact gets a link to their latest session replay.
Where to find it: account Settings, card HubSpot (account managers connect and disconnect; everyone in the account sees the state). On SaaS installations the plan must include HubSpot integration (hubspot.enabled).
- In HubSpot (Settings › Integrations › Private apps › Create) create a private app with the scopes
crm.objects.contacts.read,crm.objects.contacts.writeandcrm.schemas.contacts.write, and copy its access token. - Paste it as Private app token and press Connect HubSpot. Replora checks it with HubSpot at once and creates two contact properties:
| Property | Label | Holds |
|---|---|---|
replora_last_replay | Latest session replay | The dashboard link to the session |
replora_last_seen | Latest recorded visit | When the visit was |
- On your site, identify visitors by email:
js
__sr.push(['identify', '[email protected]']);
// or with another id and the email as a trait:
__sr.push(['identify', 'user-4217', { email: '[email protected]' }]);Rules: contacts are never created, only updated (people HubSpot already knows); one update per session and email address; the connection reports the HubSpot portal id, how many contacts were updated, the last sync and the last error (GET /integrations/hubspot). The connection is removed with the account. API: Integrations.
Google Analytics events
Every event pushed to window.dataLayer tags the session ga:<event name>, so you can find sessions by what Analytics saw (e.g. the ga:purchase tag):
- Google Tag Manager's
dataLayer.push({ event: 'add_to_cart' }), - gtag's
gtag('event', 'add_to_cart', { … }).
Details: GTM's own events (gtm.js, gtm.dom, gtm.load …) are left out; each name counts once per page, at most 30 names a page, names up to 60 characters. Events already in dataLayer when the tracker starts count too. If the page has no dataLayer, the tracker creates an empty one (as Tag Manager does).
Turn it off with __sr.push(['disableGACapture']) (or disableGACapture: true in the npm package).
Other ways to connect
| Need | Use |
|---|---|
| A support tool that links to the visitor's replay | getSessionLink on your page, stored with the ticket |
| Your own reports or data warehouse | The REST API with a recordings:read token; the sessions CSV export |
| React to problems in your own system | A webhook alert |
