On this page
Receive a signed sandbox request
This signed walkthrough uses the public sandbox and fictional leads only.
- Read the raw body before any JSON parser touches it.
- Verify the signature and the timestamp.
- Deduplicate on
webhook-id. - Queue the work and answer 2xx within 20 seconds.
- 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;
}# Synthetic handler; configured production signing uses this format with a private secret.
def on_lead(headers, raw_body):
if not verify(headers, raw_body): # 1, 2
return 401
if seen(headers["webhook-id"]): # 3
return 200
queue.add(raw_body) # 4
return 204// Synthetic handler; configured production signing uses this format with a private secret.
function on_lead(array $headers, string $rawBody): int {
if (!verify($headers, $rawBody)) return 401; // 1, 2
if (seen($headers['webhook-id'])) return 200; // 3
queue_add($rawBody); // 4
return 204;
}// Synthetic handler; configured production signing uses this format with a private secret.
async Task<int> OnLead(IHeaderDictionary headers, byte[] rawBody)
{
if (!Verify(headers, rawBody)) return 401; // 1, 2
if (await Seen(headers["webhook-id"])) return 200; // 3
await queue.AddAsync(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.
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
- Remove the
whsec_prefix and base64-decode the rest. Those bytes are the key. - Join the signed content:
id.timestamp.body, with the body exactly as received. - Take HMAC-SHA256 and base64-encode it.
- Compare with each space-separated value in
webhook-signatureafter itsv1,prefix, in constant time. - Check the time. Refuse a
webhook-timestampmore 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.
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.
204 No ContentRetries
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.
| After failure | Waits up to | Latest by |
|---|---|---|
| 1 | 30 s | 30 s |
| 2 | 1 min | 1 min 30 s |
| 3 | 2 min | 3 min 30 s |
| 4 | 4 min | 7 min 30 s |
| 5 | 8 min | 15 min 30 s |
| 6 | 16 min | 31 min 30 s |
| 7 | 32 min | 1 h 3 min 30 s |
| 8 and on | 1 h | every hour |
5xx, 408, 429 retried
timeout, network retried
other 4xx stops
3xx stops, not followedDuplicates
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.
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.
-- 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.
webhook-id: 00000000-0000-4000-8000-000000000005
isResend: false
sequence: 1
webhook-id: 00000000-0000-4000-8000-000000000005 same
isResend: true changed
sequence: 2 changedRotate 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.
webhook-signature:
v1,<new secret signature>
v1,<old secret signature>
one header, separated by a spaceWhen 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.
POST chosen synthetic simulation
retries client controlled, not scheduled here
records no dealership delivery record
alerts no dealership notification
data fictional test leads only