POST /api/ingest/v1

Quick start

1. Create a project key at Settings → Listening and copy the bsk_… secret on first reveal (you only see it once).
2. Send POST /api/ingest/v1 with the headers below and a JSON body of { visitor_id, events: [...] }.
3. Verify the response: { ok: true, accepted: <int> }. Retry on 5xx.

Headers

Signature recipe

Build the signed payload as <timestamp>.<raw_body> (literal dot). HMAC-SHA256 with the secret, encode the result as lowercase hex, prepend t=…,v1=.

signed_payload = f"{timestamp}.{raw_body}"
v1             = hmac_sha256(secret, signed_payload).hex()
header         = f"t={timestamp},v1={v1}"

Sign the EXACT raw bytes you put on the wire. JSON re-serialization (e.g. an extra trailing newline from a pretty-printer) will break the signature.

Examples

curl

BODY='{"visitor_id":"v_abc","events":[{"event_type":"intent","url":"https://shop.example.com/checkout"}]}'
TS=$(date +%s)
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$Wavly_SECRET" -hex | awk '{print $2}')
curl -sS -X POST https://thewavly.com/api/ingest/v1 \
  -H "Content-Type: application/json" \
  -H "X-Wavly-Key: $Wavly_PUBLIC_KEY" \
  -H "X-Wavly-Signature: t=$TS,v1=$SIG" \
  -H "Idempotency-Key: order-9482" \
  --data-raw "$BODY"

Node (built-in crypto)

import crypto from "node:crypto";

const body = JSON.stringify({
  visitor_id: "v_abc",
  events: [{ event_type: "intent", url: "https://shop.example.com/checkout" }],
});
const ts = Math.floor(Date.now() / 1000);
const v1 = crypto
  .createHmac("sha256", process.env.Wavly_SECRET)
  .update(`${ts}.${body}`)
  .digest("hex");

const res = await fetch("https://thewavly.com/api/ingest/v1", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Wavly-Key": process.env.Wavly_PUBLIC_KEY,
    "X-Wavly-Signature": `t=${ts},v1=${v1}`,
    "Idempotency-Key": "order-9482",
  },
  body,
});
const json = await res.json();
console.log(json); // { ok: true, accepted: 1 }

Python

import hmac, hashlib, json, os, time, requests

body = json.dumps({
    "visitor_id": "v_abc",
    "events": [{"event_type": "intent", "url": "https://shop.example.com/checkout"}],
}, separators=(",", ":"))

ts = str(int(time.time()))
v1 = hmac.new(
    os.environ["Wavly_SECRET"].encode(),
    f"{ts}.{body}".encode(),
    hashlib.sha256,
).hexdigest()

r = requests.post(
    "https://thewavly.com/api/ingest/v1",
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Wavly-Key": os.environ["Wavly_PUBLIC_KEY"],
        "X-Wavly-Signature": f"t={ts},v1={v1}",
        "Idempotency-Key": "order-9482",
    },
)
print(r.json())  # {"ok": True, "accepted": 1}

Idempotency

Pass Idempotency-Key: <up-to-128-chars>. A retry with the same key returns the original { ok: true, accepted, duplicate: true } without inserting again. The key TTL is 7 days. Two different bodies under the same key are NOT detected — pick a unique key per logical event.

Errors

Rotation

Rotate your secret in Settings → Listening → Project keys → Rotate secret. The previous secret stops verifying signatures the moment rotation completes — there is no overlap window. To minimize downtime, sign with both old and new during the rollout (HMAC callers may include multiple v1= values in the header, and we'll accept any matching one).