Webhooks

Webhooks let Eraya notify your systems in real time when your A/B tests change state — created, started, paused, resumed, stopped, completed, when a test reaches statistical significance, or whenever its stats are recomputed. Instead of polling the dashboard, you give Eraya an HTTPS URL and we POST a signed JSON payload to it the moment something happens.

---

What is a webhook?

A webhook is an HTTP callback. You register an endpoint URL once; Eraya sends an HTTP POST request to that URL every time an event you subscribed to occurs. Common uses:

• Post test results into Slack, Discord, or Microsoft Teams

• Trigger downstream workflows (data warehouse loads, BI refreshes)

• Alert your team the moment a test reaches significance

• Sync test lifecycle into your own project tracker

---

Prerequisites

• An active Eraya account with a connected Shopify store

• A Growth plan subscription or higher (webhooks are gated to Growth+)

• A publicly reachable HTTPS endpoint that can accept POST requests

---

Setting up a webhook

1. Go to Settings → Webhooks in the Eraya dashboard.

2. Click + Add webhook.

3. Enter your Endpoint URL (must start with https://).

4. Optionally add a description (e.g. "Slack notifier for #experiments").

5. Select the events you want to receive.

6. Click Create webhook.

Eraya automatically generates a signing secret for the subscription. Reveal it from the webhook row and copy it into your receiver's configuration — you'll use it to verify that incoming requests genuinely came from Eraya.

Use the Send test button at any time to deliver a sample test.ping payload and confirm your endpoint is reachable.

---

Event types

Event	When it fires
test.created	A new test is created (in any status, usually draft)
test.started	A test moves from draft → active
test.resumed	A test moves from paused → active
test.paused	A test moves from active → paused
test.stopped	A test is manually completed by a user
test.completed	A test is completed automatically (e.g. by its scheduled end date)
test.reached_significance	A variation crosses the statistical-significance threshold for the first time
test.stats_updated	Test statistics were recomputed (high volume — see note below)

About test.stats_updated: stats are recomputed on a daily schedule for every active test, plus on demand whenever a test's status, cost data, or window changes. Subscribing to this event means roughly one delivery per active test per day, plus extras. Only subscribe if you specifically need every recompute.

You can subscribe to specific events, or use * to receive all of them.

---

Payload format

Every delivery has the same envelope. The data object varies by event type.

{
  "id": "evt_5b58f53c-8e38-4726-bb41-612fb53fd6ab",
  "type": "test.resumed",
  "createdAt": "2026-05-16T02:18:32.489Z",
  "storeId": "69ec0570c48f9e90a9b642a0",
  "data": {
    "testId": "6a066fdc67cf643b6385a8d7",
    "testType": "splitUrl",
    "name": "Homepage hero test",
    "status": "active",
    "previousStatus": "paused",
    "startDate": "2026-05-15T00:59:08.091Z",
    "variations": [
      { "id": "a", "name": "Control", "percentage": 50, "isControl": true },
      { "id": "b", "name": "Variation 1", "percentage": 50, "isControl": false }
    ]
  }
}

For test.reached_significance and test.stats_updated, the data object additionally includes the computed comparisons, variations, asOfDate, and (for stats) computeReason and session counts.

Request headers

Header	Description
X-Eraya-Event	The event type (e.g. test.resumed)
X-Eraya-Delivery	Unique delivery ID — equals the id field; use it for idempotency
X-Eraya-Signature	HMAC signature of the raw body (see below)
User-Agent	Always Eraya-Webhooks/1.0
Content-Type	application/json

Your endpoint should respond with a 2xx status code as quickly as possible. Any non-2xx response (or a timeout after 10 seconds) is treated as a failed delivery and retried.

---

Verifying the signature

Every request includes an X-Eraya-Signature header of the form sha256=<hex>, where the value is an HMAC-SHA256 of the raw request body keyed with your subscription's signing secret.

Important: compute the HMAC over the raw, unparsed request body bytes. If you parse the JSON and re-serialize it before hashing, whitespace and key order will differ and the signature will not match.

Node.js (Express)

const crypto = require('crypto')

// Capture the raw body before JSON parsing consumes it
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf }
}))

app.post('/webhooks/eraya', (req, res) => {
  const secret = process.env.ERAYA_WEBHOOK_SECRET // the whsec_... value
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(req.rawBody)
    .digest('hex')

  const got = req.header('X-Eraya-Signature') || ''
  const valid =
    got.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))

  if (!valid) return res.status(401).end()

  // Signature verified — process req.body
  res.status(200).end()
})

Python (Flask)

import hmac, hashlib
from flask import request, abort

@app.post("/webhooks/eraya")
def eraya_webhook():
    raw = request.get_data()  # raw bytes
    expected = "sha256=" + hmac.new(
        SECRET.encode(), raw, hashlib.sha256
    ).hexdigest()
    got = request.headers.get("X-Eraya-Signature", "")
    if not hmac.compare_digest(got, expected):
        abort(401)
    # verified — handle request.json
    return "", 200

Always use a constant-time comparison (timingSafeEqual / compare_digest), not ==.

---

Delivery, retries, and failures

• Timeout: each attempt waits up to 10 seconds for a 2xx response.

• Retries: failed deliveries are retried automatically with backoff, up to 5 attempts, before being moved to a dead-letter queue.

• Idempotency: retries reuse the same X-Eraya-Delivery / id. A subscription that already received a delivery successfully will not be POSTed to again for the same event. Use this ID to de-duplicate on your side.

• Auto-disable: if a subscription accumulates 20 consecutive failed deliveries, Eraya automatically disables it. Re-enable it from the dashboard once your endpoint is healthy — this resets the failure counter.

---

Delivery history

Open the History view on any webhook to see recent deliveries (retained for 30 days), including:

• Event type and timestamp

• Delivery status (success, failed, dead) and the HTTP status code returned

• The response body your endpoint returned (truncated)

• Any error message

You can Redeliver any past event manually — this re-queues the original payload for a fresh delivery attempt.

---

Rotating the signing secret

From a webhook row, click Rotate to generate a new signing secret. The old secret is invalidated immediately, so update your receiver's configuration before the next event fires. Rotate the secret if you suspect it has been exposed.

---

Best practices

• Verify every request. Reject anything whose signature doesn't match.

• Respond fast. Acknowledge with 2xx immediately and do heavy processing asynchronously; slow endpoints get retried and may auto-disable.

• Be idempotent. Use X-Eraya-Delivery to ignore duplicates from retries.

• Subscribe narrowly. Only subscribe to the events you need — especially avoid test.stats_updated unless you require every recompute.

• Monitor failures. Watch the delivery history and the consecutive-failure count so you can fix issues before a subscription is auto-disabled.

---

Troubleshooting

Symptom	Likely cause
No deliveries arriving	Subscription is disabled, the store isn't on Growth+, or the event isn't subscribed
Signature never matches	Hashing a parsed/re-serialized body instead of the raw bytes, or using the wrong/rotated secret
Subscription keeps disabling	Endpoint returning non-2xx or timing out (>10s); check delivery history for the response code
Duplicate events	Not de-duplicating on X-Eraya-Delivery; retries reuse the same delivery ID