On this page
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.
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" },
…
}204 No ContentWho 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.
Your system can… Use
receive a request HTTPS webhook
make a request Pull API
read a mailbox Email JSONWorks with
| Needs | Detail |
|---|---|
| Your system | A client for the public test API, or an optional local sample receiver |
| Address | The Test API panel sends only to this portal's /sandbox endpoints. A local receiver is a separate synthetic exercise. |
| Trust | The test secret is public. Its signature exercises the format; it does not authenticate real lead data. |
| Set up by | No account or dealership configuration is needed for this sandbox |
| Your side | Use only fictional leads and the published test secret. Keep signature verification enabled. |
# 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
| Block | Holds | About a person |
|---|---|---|
customer | Name, email, phone, address, date of birth, nationality | Yes |
consent | Recorded privacy, terms and marketing choices | Yes |
selections, additionalFormFields | Finance and trade-in inputs, free text from the form | Yes |
payment, pricing | Outcome, amounts, provider reference | Yes, through the customer |
vehicle | Identity including VIN, specs, options | Yes, through the customer |
dealer | Locations, codes, notification mailbox | Only a named mailbox |
links | Lead and vehicle addresses | Holds the customer id |
org, event, provider | Business context | No |
| Item | Why |
|---|---|
| Status code | Decides whether the lead is done or retried |
| Up to 64 KB of the body | Kept with the delivery record. Keep personal data out of your reply. |
Retry-After | Honoured up to 1 hour |
{
"privacyNoticePresented": true,
"privacyNoticeVersion": "terms-v1",
"termsAccepted": true,
"termsAcceptedAt": "2026-11-02T09:13:52Z",
"termsVersion": "terms-v1",
"marketingEmailConsent": true,
"marketingSmsConsent": null,
"marketingWhatsappConsent": null,
"thirdPartyTransferConsent": null
}true recorded yes
false recorded no
null no record: treat as unknownQuickstart
- Add a route that reads the raw body. A parsed and re-serialized body will not match the signature.
- Set the public test secret. Use the sandbox value in
ARCHITERA_WEBHOOK_SIGNING_SECRET, never for real lead data. - Verify, then deduplicate on
webhook-id. Repeat the same signed synthetic request to exercise this receiver behavior. - Answer 2xx, and do the work after. You have 20 seconds.
- 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));
# receiver.py: pip install flask, set ARCHITERA_WEBHOOK_SIGNING_SECRET
# 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 base64, hashlib, hmac, json, os, time
from flask import Flask, request
secret = base64.b64decode(
os.environ["ARCHITERA_WEBHOOK_SIGNING_SECRET"].removeprefix("whsec_")
)
seen = set() # ephemeral deduplication for this synthetic exercise
app = Flask(__name__)
app.config["MAX_CONTENT_LENGTH"] = 1_572_864 # the largest body read, 1.5 MiB; more gets 413
def verify(headers, raw_body):
msg_id = headers.get("webhook-id")
timestamp = headers.get("webhook-timestamp")
if not msg_id or not timestamp or not timestamp.isascii() or not timestamp.isdigit():
return False
try:
seconds = int(timestamp)
except (ValueError, OverflowError):
return False
now = int(time.time())
if seconds < now - 300 or seconds > now + 300:
return False
signed = f"{msg_id}.{timestamp}.".encode() + raw_body
digest = hmac.digest(secret, signed, hashlib.sha256)
expected = base64.b64encode(digest).decode()
return any(
value.startswith("v1,") and hmac.compare_digest(value[3:], expected)
for value in headers.get("webhook-signature", "").split(" ")
)
@app.post("/webhooks/architera")
def receive():
raw_body = request.get_data()
if not verify(request.headers, raw_body):
return "", 401
try:
lead = json.loads(raw_body)
except (ValueError, RecursionError):
return "", 400
if (
not isinstance(lead, dict)
or not isinstance(lead.get("event"), dict)
or not isinstance(lead["event"].get("type"), str)
or not isinstance(lead.get("customer"), dict)
or not isinstance(lead["customer"].get("id"), str)
):
return "", 400
msg_id = request.headers["webhook-id"]
if msg_id in seen: # a retry or Replay: webhook-id is the stable event.id
return "", 200
seen.add(msg_id)
print(lead["event"]["type"], lead["customer"]["id"]) # queue your work here
return "", 204
<?php
// receiver.php: set ARCHITERA_WEBHOOK_SIGNING_SECRET
// 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.
const MAX_BODY_BYTES = 1572864; // the largest body this receiver reads, 1.5 MiB
$secret = base64_decode(
preg_replace('/^whsec_/', '', getenv('ARCHITERA_WEBHOOK_SIGNING_SECRET'))
);
// Read at most one byte more than the cap: until the signature is checked the caller is not known.
if ((int) ($_SERVER['CONTENT_LENGTH'] ?? 0) > MAX_BODY_BYTES) {
http_response_code(413);
exit;
}
$rawBody = stream_get_contents(fopen('php://input', 'rb'), MAX_BODY_BYTES + 1);
if (strlen($rawBody) > MAX_BODY_BYTES) {
http_response_code(413);
exit;
}
$id = $_SERVER['HTTP_WEBHOOK_ID'] ?? '';
$timestamp = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '';
$values = explode(' ', $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '');
$expected = 'v1,' . base64_encode(
hash_hmac('sha256', "$id.$timestamp.$rawBody", $secret, true)
);
$valid = false;
foreach ($values as $value) {
$valid = $valid || hash_equals($expected, $value);
}
if ($id === '' || preg_match('/\A[0-9]+\z/', $timestamp) !== 1 ||
abs(time() - (int) $timestamp) > 300 || !$valid) {
http_response_code(401);
exit;
}
// Deduplicate on $id, then queue $rawBody for your worker.
http_response_code(204);
// Program.cs: ASP.NET Core minimal API, .NET 8
// 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.
using System.Security.Cryptography;
using System.Text;
var secret = Convert.FromBase64String(
Environment.GetEnvironmentVariable("ARCHITERA_WEBHOOK_SIGNING_SECRET")!
.Replace("whsec_", ""));
const int MaxBodyBytes = 1_572_864; // the largest body this receiver reads, 1.5 MiB
var app = WebApplication.Create(args);
app.MapPost("/webhooks/architera", async (HttpRequest request) =>
{
// Count the bytes as they arrive and stop at the cap: until the signature is checked the caller is not known.
if (request.ContentLength > MaxBodyBytes) return Results.StatusCode(413);
using var buffer = new MemoryStream();
var chunk = new byte[16 * 1024];
int read;
while ((read = await request.Body.ReadAsync(chunk)) > 0)
{
if (buffer.Length + read > MaxBodyBytes) return Results.StatusCode(413);
buffer.Write(chunk, 0, read);
}
var rawBody = buffer.ToArray();
var id = request.Headers["webhook-id"].ToString();
var timestamp = request.Headers["webhook-timestamp"].ToString();
var values = request.Headers["webhook-signature"].ToString().Split(' ');
var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
if (string.IsNullOrWhiteSpace(id) || timestamp.Length == 0 ||
timestamp.Any(c => c < '0' || c > '9') ||
!long.TryParse(timestamp, out var seconds) ||
seconds < now - 300 || seconds > now + 300)
return Results.Unauthorized();
var signed = Encoding.UTF8.GetBytes($"{id}.{timestamp}.")
.Concat(rawBody).ToArray();
var expected = Encoding.UTF8.GetBytes(
"v1," + Convert.ToBase64String(HMACSHA256.HashData(secret, signed)));
var valid = values.Any(value => CryptographicOperations.FixedTimeEquals(
Encoding.UTF8.GetBytes(value), expected));
if (!valid) return Results.Unauthorized();
// Deduplicate on id, then queue rawBody for your worker.
return Results.NoContent();
});
app.Run();
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.
| Header | Holds |
|---|---|
webhook-id | The same UUID as event.id, stable across retries and Replay |
webhook-timestamp | Unix seconds at the time of this attempt |
webhook-signature | v1, 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.
00000000-0000-4000-8000-000000000005.1793610847.{"schema":"architera.
lead/v1","schemaVersion":…webhook-signature:
v1,zM7hDQNSF3SrcZpwC/miAW+/2LmxSAzc5hk1Hoh2EoE=Events
| Type | Sent when |
|---|---|
lead.created | A lead starts from any other source, such as a chat, a call or WhatsApp. vehicle and pricing are null. |
atlas.enquiry_submitted | A buyer asks about a car in stock |
atlas.checkout_submitted | A buyer finishes checkout on a car in stock |
forgex.enquiry_submitted | A buyer asks about a configured car |
forgex.checkout_submitted | A 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.
{
"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 return | Recorded as | Retried | Fix |
|---|---|---|---|
| 2xx | accepted | No | None needed |
| 408, 429, 5xx | http_error | Yes | Recover. A Retry-After is honoured. |
| Other 4xx | http_error | No | Fix the receiver, then replay |
| 3xx | refused_permanent, blocked_redirect | No | Redirects are not followed. Set the final URL. |
| No answer in 20 s | timeout | Yes | Answer first, work after |
| DNS or network failure | transport_error | Yes | Check the hostname and certificate |
| URL not allowed | refused_permanent, blocked_private_address, blocked_port, blocked_scheme | No | Use a public HTTPS address |
204 No Content accepted, done
503 Service Unavailable retried
400 Bad Request stops, a person is told
301 Moved Permanently stops, not followedLimits 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.
| Limit | Value |
|---|---|
| One attempt | 20 seconds: 5 to connect, 10 to headers, 5 to read the body |
| First wait | Up to 30 seconds, and the ceiling doubles each time |
| Longest wait between attempts | 1 hour |
| Retry window | 24 hours, up to 72 if the connection sets it |
| Reply read | 64 KB |
| Pause after repeated failure | After 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. |
first wait up to 30 s
then doubles 60 s, 2 min, 4 min…
ceiling 1 h
window 24 h, at most 72 hTest data and simulations
The test API needs no account. Its key and secret are public, and work nowhere else.
| Test key | alk_test_public_sandbox |
|---|---|
| Test secret | whsec_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.
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.jsonSignature 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.
if (lead.isTest) {
log.info("test lead", lead.customer.id);
return; // never reaches a salesperson
}Changelog
- 1.4.0.
event.idis the stable business event UUID. Signed HTTPS requests use it aswebhook-id; it stays the same across retries and Replay while the delivery identity and sequence can change. - 1.3.0. Five
consentkeys can benull, meaning no record exists. Read it as unknown, never asfalse. - 1.2.0. New event
lead.created.vehicleandpricingcan benull, andprovider.serviceis free text. - 1.1.0. Prices split into
pricing.displayed, what the buyer saw, andpricing.oem, the manufacturer's figures.
No retire date is set for v1.
+ "event": { "id": "00000000-0000-4000-8000-000000000005", … }
webhook-id: 00000000-0000-4000-8000-000000000005 // stable across retries and ReplayDownloads
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