<!-- /connections/https-webhook.md -->

*Architera to Your 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 2026*

**Sandbox request**

```http
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+…

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

**Sandbox reply**

```http
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

| 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. |

**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*

| 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 |

*Into Architera, from each reply*

| 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 |

**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](#w-test) 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](/guides/webhooks) covers every step in depth, and has a signature checker.

**Receiver language: Node**

```
// 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 language: Python**

```
# 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

```

**Receiver language: PHP**

```
<?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);

```

**Receiver language: .NET**

```
// 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](https://www.standardwebhooks.com/). 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.

[Check a signature in your browser](/guides/webhooks#g-verify)

**What is signed**

```
00000000-0000-4000-8000-000000000005.1793610847.{"schema":"architera.lead/v1",…
```

**Sent as**

```
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.

**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 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 |

**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.

| 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. |

[The full retry schedule](/guides/webhooks#g-retries)

**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 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](#w-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: accept**

```bash
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
```

**Test API: reject**

```bash
curl -X POST https://developer.architera.ai/sandbox/webhook/reject \
  -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
```

**Test API: slow**

```bash
curl -X POST https://developer.architera.ai/sandbox/webhook/slow \
  -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
```

The signature is shortened in this example. The page's Copy button copies a command signed for the moment you copy it. To sign by hand, follow [Verify the signature](/guides/webhooks#g-verify).

## 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.

- [ ] Only fictional test data reaches this receiver or the public test API.
- [ ] It verifies `webhook-signature` against the raw body, and answers 401 when that fails.
- [ ] It refuses a `webhook-timestamp` more than five minutes from now.
- [ ] It stores `webhook-id` and treats a repeat as success.
- [ ] It answers within 20 seconds, with the work queued behind it.
- [ ] It handles `null` in every nullable key, including `vehicle` and `pricing`.
- [ ] It reads `null` in `consent` as unknown, never as consent.
- [ ] The fictional lead is marked `isTest: true` and stays out of real work.
- [ ] Repeating the same signed synthetic request made no second record.
- [ ] The public test key and secret are never used to protect real data.
- [ ] Production configuration and private credentials are verified separately; this sample remains a synthetic exercise.

**Keep tests out of real work**

```
if (lead.isTest) {
  log.info("test lead", lead.customer.id);
  return; // never reaches a salesperson
}
```

## Changelog

- 2026-11-06: **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.
- 2026-10-17: **1.3.0.** Five `consent` keys can be `null`, meaning no record exists. Read it as unknown, never as `false`.
- 2026-08-31: **1.2.0.** New event `lead.created`. `vehicle` and `pricing` can be `null`, and `provider.service` is free text.
- 2026-08-26: **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.json`](/samples/sample-lead.v1.json): The fictional lead on this page
- [`receiver.mjs`](/samples/receiver.mjs): Sandbox-only Node receiver, no dependencies
- [`receiver.py`](/samples/receiver.py): Sandbox-only Python receiver, Flask

**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
```
