Skip to content

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.

8 minutesDevelopersSingle user · SaaS

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.

FieldValuesNotes
NameUp to 120 charactersShown in every notification.
Tell me aboutA JavaScript error · A failed request · A rage click · A dead click · A session tag · A visit to a pageThe trigger.
Trigger valueMessage contains (optional), Address contains (optional), tag name and Value (optional), Address containsUp to 500 characters (tag names up to 64). Required for page visits.
Email toUp to 10 addresses, separated by commas
Slack incoming webhookhttps://hooks.slack.com/…Must be a Slack incoming webhook address.
Webhookhttps://…, up to 500 characters"A JSON POST, signed with the header X-Replora-Signature."
How oftenAt most once every 5 minutes, 15 minutes, hour (default), 6 hours or dayThe API accepts 1–10 080 minutes.
On / OffTurned 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"
}
FieldMeaning
eventalert.triggered, or alert.test for the Test button (the session is then 00000000-0000-4000-8000-000000000000).
alertThe alert's id and name.
siteThe website's id and name.
sessionThe matching session's id (UUID).
detailWhat matched, in one line: the error message, METHOD URL → status of a failed request, the clicked element's label, the tag, or the page.
atWhen it happened (ISO 8601, UTC).
moreOther sessions that matched since the last notification.
replay_urlThe replay in the dashboard, starting just before the match (?t= in ms since epoch).

Delivery rules:

  • Answer with any 2xx status 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 in GET /sites/{site}/alerts) and doesn't stop the other channels.
  • Webhook URLs must use https and resolve to public addresses only. Private and local addresses (localhost, 10.x, 192.168.x …) are allowed only where REPLORA_ALERTS_PRIVATE_WEBHOOKS allows 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).

  1. In HubSpot (Settings › Integrations › Private apps › Create) create a private app with the scopes crm.objects.contacts.read, crm.objects.contacts.write and crm.schemas.contacts.write, and copy its access token.
  2. Paste it as Private app token and press Connect HubSpot. Replora checks it with HubSpot at once and creates two contact properties:
PropertyLabelHolds
replora_last_replayLatest session replayThe dashboard link to the session
replora_last_seenLatest recorded visitWhen the visit was
  1. 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 ​

NeedUse
A support tool that links to the visitor's replaygetSessionLink on your page, stored with the ticket
Your own reports or data warehouseThe REST API with a recordings:read token; the sessions CSV export
React to problems in your own systemA webhook alert

Replora: see what your visitors see.