# Trap 5. Subscribed to events, receiving nothing

This trap arrives later than the first ones — once the application works and needs to learn
about changes in other people's vaults. It is treacherous because **everything looks healthy**:
the subscription is listed as active, the service answers, the logs are silent.

---

## How notification works

The W3DS Awareness service (AaaS) sends your application a **webhook** — a POST to your address
— every time a record changes in a vault you are watching. What it contains is not the data but
a **pointer**: whose vault, which envelope. You then read the data from the eVault yourself.

A subscription looks like this:

```json
{
  "id": "7ed2509d-…",
  "targetUrl": "https://your-application/api/webhook",
  "active": true,
  "secret": null
}
```

**You probably do not have to create it.** AaaS reconciles, on every launch and periodically,
a catch-all subscription for each platform currently in the registry, pointing at
`<platform>/api/webhook`. So implement that route first and watch whether packets arrive before
asking anyone for anything. Creating and patching subscriptions by hand needs an AaaS API key —
see `traps/01-access-model.md` for how the person obtains one, and why they must never paste it
into a chat message.

---

## The trap: `secret: null` plus strict verification = zero deliveries

Two independent places, and a mistake in either produces the same symptom — silence.

**1. The subscription has no secret set.** Then AaaS **cannot sign** the delivery: it arrives
with no `x-aaas-signature` header.

**2. Your handler requires a signature.** The natural first instinct — "no signature, so it's a
stranger, 401" — combined with point 1 means you reject **100%** of deliveries. Every one.
Always.

And all that time `GET /api/subscriptions` reports `"active": true`. Nobody will tell you that
deliveries are not landing.

**Measured 2026-09-25:** an application was silent for several days, and "the subscription is
active" was the main reason people looked in the wrong place. Worse emerged alongside it: AaaS
sends **some deliveries unsigned even when the subscription does have a secret**. A neighbouring
team with strict verification lost **349 thousand** deliveries that way — their service answered
401, AaaS retried, and every lost event was a notification that never reached a person.

---

## How to do it properly

### First: set a secret on the subscription

```bash
curl -X PATCH "$AWARENESS_API_URL/api/subscriptions/<id>" \
  -H "Authorization: Bearer $AWARENESS_KEY" \
  -H "content-type: application/json" \
  -d "{\"secret\":\"$AAAS_WEBHOOK_SECRET\"}"
```

Check that it was written:

```bash
curl -s -H "Authorization: Bearer $AWARENESS_KEY" \
  "$AWARENESS_API_URL/api/subscriptions" | grep -o '"secret":[^,]*'
```

### Second: the handler accepts unsigned but refuses a forgery

Those are two different questions and cannot be settled in one line:

```ts
function verifyWebhook(raw: string, sig?: string): boolean {
  if (!SECRET) return true;                       // no secret configured — development mode
  if (!sig) return process.env.WEBHOOK_REQUIRE_SIGNATURE === "1";  // no signature → accept
  return timingSafeEqual(hmac(raw, SECRET), sig); // a signature present → it must match
}
```

- Signature **present** → it must be valid. A forgery is always rejected.
- Signature **absent** → accept, unless you deliberately turned on strict mode.

Why this is not a hole: the webhook body carries only a pointer. The real data you re-read from
the eVault **with your own access**. An unsigned pointer can cost you an extra read; it cannot
cost you a forged write. Authenticity lives where the data is, not in the notification about it.

Two more receiver obligations:

- **Ack packets you do not consume with a 200.** A catch-all subscription receives every
  ontology, and any non-2xx stays retryable for 24 hours, after which it is dead-lettered.
- **Be idempotent on the delivery's `eventId`**, not on the MetaEnvelope `id` — delivery is
  at-least-once by design.

---

## If there are no deliveries — the order to check in

Exactly this order, cheapest first:

1. **Your own subscription.** `GET /api/subscriptions` — find **your** `targetUrl` and look at
   **two** fields: `active` and `secret`. An active subscription with no secret is the typical
   cause.
2. **Your own handler.** Knock on your own webhook from outside, unsigned:
   ```bash
   curl -s -o /dev/null -w "%{http_code}\n" -X POST https://your-address/api/webhook \
     -H 'content-type: application/json' -d '{}'
   ```
   A 401 means you are rejecting everything yourself and the notification service is innocent.
3. **The web server's logs.** Count POSTs to `/api/webhook` by host. If neighbouring
   applications are receiving deliveries and you are not, the problem is yours, not the
   network's.
4. **Only now** go to the AaaS owners — with dates, counts and the subscription id, not with
   "your thing is broken".

The last point is not politeness. Until the first three are done, the odds of blaming someone
else's service for your own mistake are very high.

---

## Catching up on what you missed

Webhooks are a low-latency hint, not the durable channel. The history is
`GET /api/packets?from=<ISO-8601>` (also filterable by `ontology`, comma-separated, and
`evault`), paged with `limit` and an opaque `cursor` taken from the previous response's
`nextCursor`. Keep a durable `receivedAt` checkpoint and walk forward from it on every start;
that is what makes a restart, a deploy or a day of failed deliveries recoverable rather than a
permanent hole.

File uploads appear here too, stamped `schemaId: "w3ds-file-v1"` — a **slug, not a UUID**, so
pass it verbatim when filtering.

---

## The check that closes this gate

The person changes something in their data in a **different** application — and **your
application learns about it on its own**, with no page reload and no manual refresh. If a
"refresh" button is needed, notification is not working, however the subscription looks.
