<!-- /guides/webhooks.md -->

# 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](/access#a-production) separately.

*Applies to the HTTPS webhook sandbox*

**Handler language: Node**

```
// 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;
}
```

**Handler language: Python**

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

**Handler language: PHP**

```
// 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;
}
```

**Handler language: .NET**

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

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

Paste a secret, a webhook-id, a webhook-timestamp, a webhook-signature and the raw body; the checker runs in the browser and sends nothing.

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

**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,<signature with new secret> v1,<signature with old secret>
```

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