Architera Developers
On this page

Receive a signed sandbox request

This signed walkthrough uses the public sandbox and fictional leads only.

  1. Read the raw body before any JSON parser touches it.
  2. Verify the signature and the timestamp.
  3. Deduplicate on webhook-id.
  4. Queue the work and answer 2xx within 20 seconds.
  5. Assume nothing about order. Use event.occurredAt.

Production HTTPS delivery supports Standard Webhooks signing when configured. These handlers demonstrate the format with synthetic data; use a private destination secret and durable storage for a production receiver. Confirm production authentication separately.

// Synthetic handler; configured production signing uses this format with a private secret.
async function onLead(headers, rawBody) {
  if (!verify(headers, rawBody)) return 401;   // 1, 2
  if (await seen(headers["webhook-id"])) return 200; // 3
  await queue.add(rawBody);                    // 4
  return 204;
}

The request

One lead, one POST, sent as application/json. The synthetic examples use the same three Standard Webhooks headers as production HTTPS delivery with signing configured.

The sender supplies idempotency-key for a delivery. For signed HTTPS requests, webhook-id equals the body's stable event.id. It remains the same across retries and Replay even when the delivery id or sequence changes.

Read at most 1.5 MiB (1,572,864 bytes) of a request, counting as it arrives, and answer 413 above that. Until the signature is checked you do not know who is calling, and the cap keeps a stranger from making you hold more than this in memory. The sample receivers do it.

Sandbox headers
POST /sandbox/webhook/accept HTTP/1.1
host: developer.architera.ai
content-type: application/json
idempotency-key: architera/lead/fab4a342efc153003fcb5569592c405f240f175ff218c6e8eeb9b6ba53265402
webhook-id: 00000000-0000-4000-8000-000000000005
webhook-timestamp: 1793610847
webhook-signature: v1,zM7hDQNSF3SrcZpwC/miAW+/2LmxSAzc5hk1Hoh2EoE=

Verify the signature

  1. Remove the whsec_ prefix and base64-decode the rest. Those bytes are the key.
  2. Join the signed content: id.timestamp.body, with the body exactly as received.
  3. Take HMAC-SHA256 and base64-encode it.
  4. Compare with each space-separated value in webhook-signature after its v1, prefix, in constant time.
  5. Check the time. Refuse a webhook-timestamp more than five minutes from now. An attacker who records a request cannot then send it again later.

The checker is loaded with the test secret and the sample request on this page. Change one byte of the body and see it fail. Then re-sign it with the current time and see every check pass.

The official Standard Webhooks libraries do all of this in one call, for JavaScript, Python, PHP, C#, Go, Java and more.

Signature checker runs in this browser. Nothing is sent.

Respond fast

For a sample receiver, inspect or queue only fictional test data and answer promptly. The public sandbox stores no lead and does no CRM work.

Any 2xx counts as delivered. The body of your reply is not read for meaning, so keep it short and free of personal data.

A good reply
204 No Content

Retries

The separate production HTTPS transport retries failed attempts with exponential backoff and full jitter: each wait is random, between zero and a ceiling that doubles from 30 seconds to one hour. Jitter stops every lead from one bad minute landing back on you in the same second.

Production retries continue for 24 hours by default, or up to 72 if the connection is set that way. 408, 429 and any 5xx are retried, as are timeouts and network failures. A Retry-After header is honoured, up to one hour.

Production delivery runs in passes, so a gap can run a few minutes past its ceiling. The public sandbox does not schedule retries.

Retry schedule
After failureWaits up toLatest by
130 s30 s
21 min1 min 30 s
32 min3 min 30 s
44 min7 min 30 s
58 min15 min 30 s
616 min31 min 30 s
732 min1 h 3 min 30 s
8 and on1 hevery hour
Retried, or not
5xx, 408, 429       retried
timeout, network    retried
other 4xx           stops
3xx                 stops, not followed

Duplicates

Store the stable event.id, also sent as webhook-id on signed HTTPS requests, with the record in one durable transaction. A retry or Replay answers 2xx without a second record. The sample receivers use only an ephemeral set for the synthetic exercise; replace it with durable deduplication before handling real leads.

Store the id with the lead
CREATE TABLE webhook_receipts (
  webhook_id  TEXT PRIMARY KEY,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

BEGIN;
INSERT INTO webhook_receipts (webhook_id) VALUES ('00000000-0000-4000-8000-000000000005')
  ON CONFLICT DO NOTHING;
-- no row inserted: a repeat. Answer 2xx and stop.
-- one row inserted: store the lead, then commit.
COMMIT;

Ordering

Leads can arrive out of order, because each retries on its own schedule. Sort by event.occurredAt, never by arrival. sequence counts sends of the same lead, so it says nothing about two different leads.

Keep the newest state
-- apply only if this event is newer
UPDATE leads SET state = :state, occurred_at = :occurred_at
 WHERE id = :id AND occurred_at < :occurred_at;

Replay

A dealership operator can Replay a finished delivery. event.id and the signed webhook-id stay the same, isResend becomes true and sequence increases; a receiver should not create a second record. Replay is refused for an erased buyer. The public sandbox has no dealership replay action and stores no delivery history.

Never send real customer data, including erased-customer data, to the public sandbox.

Retry and Replay keep the event identity
webhook-id: 00000000-0000-4000-8000-000000000005
isResend:   false
sequence:   1

webhook-id: 00000000-0000-4000-8000-000000000005   same
isResend:   true                       changed
sequence:   2                          changed

Rotate the secret

This sandbox uses one published test secret. Standard Webhooks verifiers can compare a space-separated signature list, as illustrated below. Configured production signing currently uses one active destination secret; overlap with two signatures is not implemented. This portal provides no production secret-issuance or rotation workflow.

Verifier format, not production rotation
webhook-signature:
v1,<new secret signature>
v1,<old secret signature>

one header, separated by a space

When retries run out

The sandbox does not queue deliveries, create dead letters or alert dealership operators. Its fixed responses let you exercise client handling without real leads.

The gateway supports operator Replay and production failure notifications, subject to its configured destination and recipients. Confirm deployment and recovery for the actual dealership connection separately; this synthetic walkthrough does not prove them.

Sandbox outcomes
POST       chosen synthetic simulation
retries    client controlled, not scheduled here
records    no dealership delivery record
alerts     no dealership notification
data       fictional test leads only