Developers

// setup-ellieforms.mjs: node setup-ellieforms.mjs  (Node 18 or newer)
const BASE = "https://api-staging.ellieforms.com";

async function api(path, { token, body, method = body ? "POST" : "GET" } = {}) {
  const res = await fetch(BASE + path, {
    method,
    headers: { "content-type": "application/json", ...(token && { authorization: `Bearer ${token}` }) },
    body: body && JSON.stringify(body),
  });
  const data = await res.json();
  if (res.status >= 400) throw new Error(`${data.error.code}: ${data.error.message} ${data.error.fix ?? ""}`);
  return { status: res.status, data };
}

// Sign in: the owner opens the link; the token stays in this process.
const { data: session } = await api("/v1/agent/sessions", { method: "POST" });
console.log(`Open ${session.sign_in_url} and check the code is ${session.user_code}`);

let token;
let wait = session.interval;
while (!token) {
  await new Promise((r) => setTimeout(r, wait * 1000));
  const { status, data } = await api(new URL(session.poll_url).pathname, { body: { device_code: session.device_code } });
  if (status === 200) token = data.token;
  else if (data.error.code === "slow_down") wait += 5;
}

const { data: site } = await api("/v1/sites", { token, body: { name: "Bakery website", url: "https://danasbakery.com" } });
const { data: form } = await api("/v1/forms", { token, body: { site_id: site.site_id, name: "Contact form" } });
console.log("Add this to your form:\n" + form.snippet);
console.log("Badge link:", form.badge_url);

// After the snippet is on your site:
const { data: test } = await api(`/v1/forms/${form.form_id}/test`, { token, body: { fields: { name: "Test", email: "test@example.com", message: "Hello" } } });
console.log("Learned fields:", test.learned_fields, test.alerts);
await api(`/v1/forms/${form.form_id}/live`, { token, method: "POST" });
console.log("Live.");

{
  "event": "messages.created",
  "delivery_id": "alr_8hW2…",
  "timing": "instant",
  "count": 1,
  "messages": [
    {
      "id": "msg_Q4m9…",
      "test": false,
      "created_at": "2026-10-20T09:15:00.000Z",
      "website": "shop.example.com",
      "form_id": "frm_7Tx1…",
      "form_name": "Contact",
      "fields": {
        "name": "Ana",
        "email": "ana@example.com",
        "message": "Do you ship to Lisbon?"
      },
      "reply_to": "ana@example.com",
      "inbox_url": "https://app.ellieforms.com/app/messages/msg_Q4m9…"
    }
  ]
}

// Web standard Request/Response: Cloudflare Workers, Next.js route handlers
// (app/api/ellieforms/route.ts), Deno, Bun, Hono.
async function fromEllieforms(rawBody: string, header: string | null, secret: string) {
  const { t, v1 } = Object.fromEntries((header ?? "").split(",").map((p) => p.split("=") as [string, string]));
  if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
  const sig = Uint8Array.from(v1.match(/../g) ?? [], (h) => parseInt(h, 16));
  return crypto.subtle.verify("HMAC", key, sig, new TextEncoder().encode(`${t}.${rawBody}`)); // constant-time
}

export async function POST(request: Request) {
  const raw = await request.text();
  if (!(await fromEllieforms(raw, request.headers.get("ellieforms-signature"), process.env.ELLIEFORMS_WEBHOOK_SECRET!))) {
    return new Response("bad signature", { status: 401 });
  }
  const delivery = JSON.parse(raw) as { delivery_id: string; messages: { id: string; fields: Record<string, string> }[] };
  for (const message of delivery.messages) {
    // skip message.id values you have already stored, then save or forward the rest
  }
  return new Response("ok");
}
// Cloudflare Workers: read the secret from env.ELLIEFORMS_WEBHOOK_SECRET instead of process.env.

# Flask
import hashlib, hmac, json, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["ELLIEFORMS_WEBHOOK_SECRET"].encode()

def from_ellieforms(raw: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > 300:
        return False
    expected = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

@app.post("/ellieforms")
def ellieforms():
    raw = request.get_data()  # raw bytes, before any parsing
    if not from_ellieforms(raw, request.headers.get("Ellieforms-Signature", "")):
        abort(401)
    for message in json.loads(raw)["messages"]:
        print(message["id"], message["fields"])  # skip ids you have already stored
    return "ok"

<?php
// ellieforms.php
$raw = file_get_contents('php://input');
$secret = getenv('ELLIEFORMS_WEBHOOK_SECRET');
parse_str(str_replace(',', '&', $_SERVER['HTTP_ELLIEFORMS_SIGNATURE'] ?? ''), $sig);

$fresh = isset($sig['t']) && abs(time() - (int) $sig['t']) <= 300;
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $raw, $secret);
if (!$fresh || !hash_equals($expected, $sig['v1'] ?? '')) {
    http_response_code(401);
    exit;
}

foreach (json_decode($raw, true)['messages'] as $message) {
    error_log($message['id'] . ' ' . json_encode($message['fields'])); // skip ids you have already stored
}
http_response_code(200);