Architera Developers
On this page
ArchiteraYour endpoint

HTTPS webhook

Explore the lead format and signed requests using the public, synthetic sandbox.

Test with fictional leads. Production HTTPS delivery supports Standard Webhooks signing when configured with a destination signing secret. The public sandbox secret below is for synthetic requests only. Confirm the destination and its private secret separately; never disable verification to accept an unsigned delivery.

Last verified 7 November 2026MarkdownWas this useful?
Sandbox request
POST /sandbox/webhook/accept HTTP/1.1
host: developer.architera.ai
content-type: application/json
idempotency-key: architera/lead/fab4a342efc1530…
webhook-id: 00000000-0000-4000-8000-000000000005
webhook-timestamp: 1793610847
webhook-signature: v1,zM7hDQNSF3SrcZpwC/miAW+…

{
  "schema": "architera.lead/v1",
  "schemaVersion": "1.4.0",
  "isTest": true,
  "org": { "slug": "example-motors" },
  "event": {
    "type": "atlas.enquiry_submitted",
    "occurredAt": "2026-11-02T09:13:54Z"
  },
  "customer": { "firstName": "Alex", "email": "alex.sample@example.com" },
  …
}
Sandbox reply
204 No Content

Who it is for

A developer implementing the lead format and signature verification, starting with synthetic requests before configuring a dealership connection.

These examples do not configure a dealership connection. Confirm its actual endpoint and authentication separately before handling real leads.

Which route
Your system can…          Use
receive a request         HTTPS webhook
make a request            Pull API
read a mailbox            Email JSON

Works with

NeedsDetail
Your systemA client for the public test API, or an optional local sample receiver
AddressThe Test API panel sends only to this portal's /sandbox endpoints. A local receiver is a separate synthetic exercise.
TrustThe test secret is public. Its signature exercises the format; it does not authenticate real lead data.
Set up byNo account or dealership configuration is needed for this sandbox
Your sideUse only fictional leads and the published test secret. Keep signature verification enabled.
Test first
# public sandbox: fictional leads only
isTest: true
url: https://developer.architera.ai/sandbox/webhook/accept

# The published test secret is not production authentication.
# Production HTTPS supports signing when configured with a private destination secret.

Data in and out

Out of Architera, in every lead
BlockHoldsAbout a person
customerName, email, phone, address, date of birth, nationalityYes
consentRecorded privacy, terms and marketing choicesYes
selections, additionalFormFieldsFinance and trade-in inputs, free text from the formYes
payment, pricingOutcome, amounts, provider referenceYes, through the customer
vehicleIdentity including VIN, specs, optionsYes, through the customer
dealerLocations, codes, notification mailboxOnly a named mailbox
linksLead and vehicle addressesHolds the customer id
org, event, providerBusiness contextNo
Into Architera, from each reply
ItemWhy
Status codeDecides whether the lead is done or retried
Up to 64 KB of the bodyKept with the delivery record. Keep personal data out of your reply.
Retry-AfterHonoured up to 1 hour
consent, as sent
{
  "privacyNoticePresented": true,
  "privacyNoticeVersion": "terms-v1",
  "termsAccepted": true,
  "termsAcceptedAt": "2026-11-02T09:13:52Z",
  "termsVersion": "terms-v1",
  "marketingEmailConsent": true,
  "marketingSmsConsent": null,
  "marketingWhatsappConsent": null,
  "thirdPartyTransferConsent": null
}
How to read it
true    recorded yes
false   recorded no
null    no record: treat as unknown

Quickstart

  1. Add a route that reads the raw body. A parsed and re-serialized body will not match the signature.
  2. Set the public test secret. Use the sandbox value in ARCHITERA_WEBHOOK_SIGNING_SECRET, never for real lead data.
  3. Verify, then deduplicate on webhook-id. Repeat the same signed synthetic request to exercise this receiver behavior.
  4. Answer 2xx, and do the work after. You have 20 seconds.
  5. Send a synthetic request. The Test API panel targets this portal's sandbox, not your server. To exercise a local sample receiver, point a freshly signed copy at that local test route and keep the exact body bytes.

The webhook guide covers every step in depth, and has a signature checker.

// receiver.mjs: run with ARCHITERA_WEBHOOK_SIGNING_SECRET set
// Sandbox-only: verify signed fictional requests with the published test secret.
// Configured production HTTPS signing uses the same format with a private secret.
// Never use the public secret for real data or disable verification for production.
import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";

const secret = Buffer.from(
  process.env.ARCHITERA_WEBHOOK_SIGNING_SECRET.replace(/^whsec_/, ""),
  "base64",
);
const MAX_BODY_BYTES = 1_572_864; // the largest body this receiver reads, 1.5 MiB
const seen = new Set(); // ephemeral deduplication for this synthetic exercise

function verify(headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  if (typeof id !== "string" || !id || typeof timestamp !== "string" || !/^\d+$/.test(timestamp)) return false;
  const seconds = Number(timestamp);
  if (!Number.isSafeInteger(seconds) || Math.abs(Math.floor(Date.now() / 1000) - seconds) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest();

  return (headers["webhook-signature"] ?? "").split(" ").some((value) => {
    const [version, signature] = value.split(",");
    if (version !== "v1" || !signature) return false;
    const given = Buffer.from(signature, "base64");
    if (given.length !== expected.length) return false;
    return timingSafeEqual(given, expected);
  });
}

// Count the bytes as they arrive and stop at the cap, before the signature is
// checked: until then the caller is not known. Without destroyOnReturn: false,
// stopping would close the connection before the 413 could be sent.
async function readBody(req) {
  if (Number(req.headers["content-length"]) > MAX_BODY_BYTES) return null;
  const chunks = [];
  let size = 0;
  for await (const chunk of req.iterator({ destroyOnReturn: false })) {
    size += chunk.length;
    if (size > MAX_BODY_BYTES) return null;
    chunks.push(chunk);
  }
  return Buffer.concat(chunks);
}

createServer(async (req, res) => {
  let rawBody;
  try {
    rawBody = await readBody(req);
  } catch {
    return; // the sender hung up in the middle of the body
  }
  if (rawBody === null) return res.writeHead(413, { connection: "close" }).end();

  if (!verify(req.headers, rawBody)) return res.writeHead(401).end();

  let lead;
  try {
    lead = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(rawBody));
  } catch {
    return res.writeHead(400).end();
  }
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
  if (!isRecord(lead) || !isRecord(lead.event) || typeof lead.event.type !== "string" ||
      !isRecord(lead.customer) || typeof lead.customer.id !== "string") {
    return res.writeHead(400).end();
  }

  const id = req.headers["webhook-id"];
  if (seen.has(id)) return res.writeHead(200).end(); // a retry or Replay: webhook-id is the stable event.id
  seen.add(id);
  console.log(lead.event.type, lead.customer.id); // queue your work here
  res.writeHead(204).end();
}).listen(Number(process.env.PORT ?? 3000));

Authentication

Signed requests follow Standard Webhooks. Their HMAC-SHA256 covers the id, timestamp and raw body. Production HTTPS delivery supports this format when configured with a destination signing secret; these examples use only the public sandbox secret.

HeaderHolds
webhook-idThe same UUID as event.id, stable across retries and Replay
webhook-timestampUnix seconds at the time of this attempt
webhook-signaturev1, then a base64 signature. The verifier accepts matching values from a space-separated list; this is not a production rotation workflow.

Production HTTPS transport uses its configured authentication mode: none, API-key header, bearer or basic, with its separately configured signing secret when signing is enabled. This portal issues no dealership credentials and does not establish that any destination is configured.

Check a signature in your browser

What is signed
00000000-0000-4000-8000-000000000005.1793610847.{"schema":"architera.
lead/v1","schemaVersion":…
Sent as
webhook-signature:
v1,zM7hDQNSF3SrcZpwC/miAW+/2LmxSAzc5hk1Hoh2EoE=

Events

TypeSent when
lead.createdA lead starts from any other source, such as a chat, a call or WhatsApp. vehicle and pricing are null.
atlas.enquiry_submittedA buyer asks about a car in stock
atlas.checkout_submittedA buyer finishes checkout on a car in stock
forgex.enquiry_submittedA buyer asks about a configured car
forgex.checkout_submittedA buyer finishes checkout on a configured car

event.id identifies the business event and stays the same across retries and Replay. deliveryId and idempotencyKey identify a delivery; do not use them to deduplicate a replayed event.

event.temperature is warm for an enquiry and hot for anything further along, such as checkout, a finance or lease request, or a reservation payment. temperatureReason names the evidence.

event, as sent
{
  "id": "00000000-0000-4000-8000-000000000005",
  "type": "atlas.enquiry_submitted",
  "journey": "enquiry",
  "occurredAt": "2026-11-02T09:13:54Z",
  "temperature": "warm",
  "temperatureReason": "enquiry_submitted",
  "temperatureRulesVersion": "1.0"
}

Errors

The production HTTPS transport classifies replies below. The sandbox returns the chosen simulation; it does not create a dealership delivery record or schedule retries.

You returnRecorded asRetriedFix
2xxacceptedNoNone needed
408, 429, 5xxhttp_errorYesRecover. A Retry-After is honoured.
Other 4xxhttp_errorNoFix the receiver, then replay
3xxrefused_permanent, blocked_redirectNoRedirects are not followed. Set the final URL.
No answer in 20 stimeoutYesAnswer first, work after
DNS or network failuretransport_errorYesCheck the hostname and certificate
URL not allowedrefused_permanent, blocked_private_address, blocked_port, blocked_schemeNoUse a public HTTPS address
Production transport outcomes
204 No Content           accepted, done
503 Service Unavailable  retried
400 Bad Request          stops, a person is told
301 Moved Permanently    stops, not followed

Limits and timing

These are the gateway transport limits, read from its delivery code. The stateless sandbox does not run that retry schedule. A production receiver still needs its own private signing secret, durable deduplication and deployment verification.

LimitValue
One attempt20 seconds: 5 to connect, 10 to headers, 5 to read the body
First waitUp to 30 seconds, and the ceiling doubles each time
Longest wait between attempts1 hour
Retry window24 hours, up to 72 if the connection sets it
Reply read64 KB
Pause after repeated failureAfter 5 timeouts or network failures in a row, sending pauses for 5 minutes, then longer, up to 1 hour. An HTTP error never causes a pause.

The full retry schedule

Production retry numbers
first wait     up to 30 s
then doubles   60 s, 2 min, 4 min…
ceiling        1 h
window         24 h, at most 72 h

Test data and simulations

The test API needs no account. Its key and secret are public, and work nowhere else.

Test keyalk_test_public_sandbox
Test secretwhsec_YXJjaGl0ZXJhLXNhbmRib3gtc2lnbmluZy1zZWNyZXQ=

Send a signed lead to one of three endpoints, to see how your sender handles each reply. A body with isTest set to false is refused, so a real lead can never land here. Save sample-lead.v1.json from Downloads into your working folder, and the Copy button gives a command that runs as it is.

The values above are public sandbox fixtures, not dealership credentials. Configured production signing uses the same signature format with its own private destination secret.

Test API
curl -X POST https://developer.architera.ai/sandbox/webhook/accept \
  -H "content-type: application/json" \
  -H "webhook-id: 00000000-0000-4000-8000-000000000005" \
  -H "webhook-timestamp: 1793610847" \
  -H "webhook-signature: v1,zM7hDQNSF3SrcZpwC/miAW+…" \
  --data-binary @sample-lead.v1.json
204 No Contentreq_01JC8Q3A1X

Signature verified. No body.

Sandbox checklist

This checks only a synthetic exercise. Production HTTPS delivery supports signing when configured, but this checklist does not establish deployment, secret configuration or a working dealership connection. Never use the public secret for real leads or remove verification to make a request pass.

Keep tests out of real work
if (lead.isTest) {
  log.info("test lead", lead.customer.id);
  return; // never reaches a salesperson
}

Changelog

  1. 1.4.0. event.id is the stable business event UUID. Signed HTTPS requests use it as webhook-id; it stays the same across retries and Replay while the delivery identity and sequence can change.
  2. 1.3.0. Five consent keys can be null, meaning no record exists. Read it as unknown, never as false.
  3. 1.2.0. New event lead.created. vehicle and pricing can be null, and provider.service is free text.
  4. 1.1.0. Prices split into pricing.displayed, what the buyer saw, and pricing.oem, the manufacturer's figures.

No retire date is set for v1.

1.4.0, stable event identity
+ "event": { "id": "00000000-0000-4000-8000-000000000005", … }
webhook-id: 00000000-0000-4000-8000-000000000005  // stable across retries and Replay

Downloads

  • sample-lead.v1.jsonThe fictional lead on this pageDownload
  • receiver.mjsSandbox-only Node receiver, no dependenciesDownload
  • receiver.pySandbox-only Python receiver, FlaskDownload
Or fetch them
curl -O https://developer.architera.ai/samples/sample-lead.v1.json
curl -O https://developer.architera.ai/samples/receiver.mjs
curl -O https://developer.architera.ai/samples/receiver.py