Notification Webhook Ux Designer

---
name: notification-webhook-ux-designer
description: 'Design the human-facing UX around outbound notifications and webhooks. For END USERS — the notification model across channels (in-app, email, push), per-category preferences, digest-vs-realtime batching for noise control, read/unread state, quiet hours, and opt-out that truly stops the messages (security/transactional still send). For DEVELOPER integrators of your webhooks — the management surface: register/edit endpoints, pick event types, a delivery log with payloads + status, test-send, replay a failed delivery, rotate the signing secret, and failing-endpoint alerts. Owns how a PERSON experiences and controls these; the wire delivery CONTRACT (envelope, signing, retry/at-least-once, versioning, subscriptions) stays with api-event-architect. Use when designing a notification center/preferences, notification noise control, or a webhook management surface. Do NOT use for the webhook delivery contract itself (api-event-architect) or generic empty/loading/error states (edge-state-ux-designer).'
---

# Notification & Webhook UX Designer

## Purpose

Two outbound channels, one recurring failure: the product either says
too much or gives no control over it. Users get seven emails for one
thread and no way to turn them off, or a critical alert lands in a
digest a day late; integrators get a webhook that fires but no way to
see whether it was delivered, no test button, no replay when their
server was down, and a secret they can't rotate without downtime. This
skill designs the HUMAN experience of both surfaces — for end users, a
notification model with real preferences, noise control, read-state, and
opt-out that works; for developer integrators, a webhook management
surface with a delivery log, test-send, replay, and secret rotation. It
owns how a person experiences, controls, and observes these events. The
wire contract underneath — envelope schema, signing, retry semantics,
versioning, subscription scoping — is `api-event-architect`'s, and this
skill designs the UX on top of it.

## Use When

- Use when: designing a notification center, notification preferences, or
  the channel strategy (in-app / email / push) for a product.
- Use when: users are drowning in notifications and you need batching,
  digests, dedup/collapse, frequency caps, or quiet hours.
- Use when: designing read/unread state, badges, dismissal, or cross-
  device notification sync.
- Use when: designing the DEVELOPER webhook surface — endpoint
  registration, event-type selection, delivery logs, test-send, manual
  replay, failing-endpoint alerts, or signing-secret rotation UX.
- Use when: designing unsubscribe/opt-out flows that must actually stop
  messages while still delivering security/transactional notices.
- Do NOT use when: the task is the webhook DELIVERY CONTRACT — envelope
  schema, signing algorithm, retry/at-least-once policy, event
  versioning, tenant-scoped subscription semantics — that is
  `api-event-architect`; this skill designs the UX over it.
- Do NOT use when: the task is generic empty/loading/error state
  rendering for these screens (the delivery-log's loading skeleton, the
  preference page's error toast) — that is `edge-state-ux-designer`.
- Do NOT use when: the "notifications" are internal system alerts to
  on-call engineers (severity, runbook, threshold) — that is
  `observability-operator` / `slo-reliability-architect`, not product UX.

## Inputs to Inspect

1. The event inventory: what happens in the product that a user or
   integrator might want to know about, and how time-sensitive each is
   (a security alert vs a "someone commented" nudge).
2. The channels available and their constraints: in-app center, email
   (deliverability, legal opt-out rules), push (permission, platform
   limits), and any SMS.
3. The webhook contract from `api-event-architect` (if present): the
   event types offered, retry/at-least-once policy, signing scheme, and
   subscription model — this skill's developer UX surfaces and controls
   exactly those, and must not contradict them.
4. Current pain: complaints of notification overload or missed critical
   notices; integrator support tickets about "did the webhook fire?",
   "can I replay?", "how do I rotate the secret?".
5. Legal/compliance constraints on messaging: unsubscribe obligations,
   the transactional-vs-marketing distinction, and consent records.

## Workflow

### End-user notifications

1. **Map events to channels and defaults.** For each notification-worthy
   event, decide default channel(s) and default on/off. Separate
   transactional/security (largely non-optional) from informational and
   marketing (opt-out, sometimes opt-in). State the default posture per
   category.
2. **Design the preference model.** Granularity users can actually reason
   about — per-category × per-channel, with sane grouping (not one
   toggle, not two hundred). One discoverable preference center; changes
   take effect immediately and are recorded.
3. **Design noise control.** Batching (realtime vs periodic digest),
   collapse/dedup ("3 people reacted" as one item, not three), frequency
   caps, and quiet hours honoring the user's timezone. This is the
   difference between a notification system people keep on and one they
   mute entirely.
4. **Design read-state and the center.** Seen vs read vs acted-on,
   mark-all-read, dismissal, badge/count semantics, and cross-device
   sync so reading on one device clears the badge on another.
5. **Design opt-out integrity.** Unsubscribe honors per-category, applies
   immediately, and is one-click where required by law; security/
   transactional notices remain deliverable and are labeled as such so
   opt-out expectations are clear. Record consent state.

### Developer webhook management

6. **Design endpoint management.** Register/edit/delete endpoints, select
   event types per endpoint, enable/disable, and separate test vs live
   environments. Surface the subscription model `api-event-architect`
   defined; do not invent a second one.
7. **Design delivery observability.** A delivery log per endpoint: event,
   timestamp, response status, latency, attempt count, and payload
   inspection with filtering. This is the first thing an integrator needs
   and the most commonly missing.
8. **Design self-service reliability tools.** Test-send / ping to a new
   endpoint, MANUAL replay of a specific failed delivery (with the
   idempotency reminder — safe replay depends on the consumer being
   idempotent, which is the contract's requirement), and failing-endpoint
   handling: alert the integrator, and surface any auto-disable-after-N-
   failures policy `api-event-architect` set (display it; don't redefine
   it).
9. **Design signing-secret UX.** Show the current secret (or its
   presence), support rotation with an overlap window so in-flight
   deliveries verifying against the old secret don't break, and make the
   verification instructions discoverable.

### Both

10. **Name the boundaries and deliver.** Delivery contract →
    `api-event-architect`; generic state rendering of these screens →
    `edge-state-ux-designer`; internal on-call alerting →
    `observability-operator`. Produce the two sub-specs in the Output
    Format.

Channel/default matrix, digest-vs-realtime decision guide, and the
webhook delivery-log field list:
[references/notification-webhook-sheet.md](references/notification-webhook-sheet.md).

## Output Format

```
NOTIFICATION & WEBHOOK UX — <product/surface>
== End-user notifications ==
Channels:      <in-app | email | push | sms> per event category
Preferences:   granularity=<per-category × per-channel>; defaults per category
               (transactional/security = non-optional, labeled)
Noise control: batching=<realtime|digest cadence>; collapse/dedup rules; freq caps; quiet hours (tz)
Read-state:    seen/read/dismiss; badges; cross-device sync
Opt-out:       per-category, immediate, one-click where required; consent recorded
== Developer webhooks (UX over api-event-architect's contract) ==
Management:    register/edit/disable; event-type selection; test vs live env
Delivery log:  event, ts, status, latency, attempts, payload view, filter
Reliability:   test-send; manual replay (idempotency noted); failing-endpoint alert +
               displayed auto-disable policy
Secret UX:     rotation with overlap window; verification docs discoverable
Boundaries:    delivery contract → api-event-architect; state rendering →
               edge-state-ux-designer; on-call alerts → observability-operator
```

## Validation Checklist

- [ ] Each event category has a default channel and on/off posture, with
      transactional/security separated from informational/marketing.
- [ ] Preferences are granular but reasonable (per-category × per-channel),
      in one center, effective immediately.
- [ ] Noise control exists: batching/digest, collapse/dedup, frequency
      caps, and timezone-aware quiet hours.
- [ ] Read-state (seen/read/dismiss), badges, and cross-device sync are
      designed.
- [ ] Opt-out honors per-category immediately and one-click where
      required; security/transactional notices remain deliverable and
      labeled.
- [ ] The webhook surface has a delivery log with payload inspection,
      test-send, and manual replay (with the idempotency caveat).
- [ ] Secret rotation uses an overlap window so in-flight deliveries
      don't break.
- [ ] The delivery contract, generic state rendering, and internal
      alerting are handed to their owning skills, not redefined here.

## Gotchas

- One master notifications toggle is not a preference model — users who
  want the one critical alert but none of the chatter are forced to pick
  all or nothing, and most pick nothing. Granularity is what keeps the
  channel alive.
- An unsubscribe link that "processes within 10 days" or silently keeps
  sending is a legal and trust failure. Opt-out is immediate and
  per-category; only genuinely transactional/security notices are exempt,
  and they must be labeled as such.
- A webhook with no delivery log is a black box: the integrator's only
  debugging tool becomes a support ticket asking you to grep your logs.
  The log is the feature.
- Manual replay without stating the idempotency requirement invites
  double-processing — replay is only safe because the consumer is
  idempotent, which is the contract's job to require and yours to
  remind.
- Rotating a signing secret with no overlap window breaks every in-flight
  and just-queued delivery still verifying against the old secret. Dual-
  valid rotation windows are the difference between a rotate button and
  an outage button.
- Digesting a time-critical alert (a security event, a failed payment)
  into tomorrow's summary is worse than no digest. Criticality overrides
  batching — decide it per category.
- Badge counts that don't sync across devices train users to distrust the
  badge; a read on the phone must clear the web badge.

## Stop Conditions

- The request is to design the webhook DELIVERY CONTRACT — envelope/
  payload schema, signing algorithm, retry and at-least-once policy,
  event versioning, subscription scoping → route to `api-event-architect`;
  this skill designs the UX over that contract and must not invent a
  conflicting one.
- The request is generic empty/loading/error state rendering for these
  screens → route to `edge-state-ux-designer`.
- The "notifications" are internal alerts to on-call engineers (severity,
  runbook, thresholds) → route to `observability-operator` /
  `slo-reliability-architect`.
- A proposed opt-out design would suppress security or legally-required
  notices, or a marketing message would be sent without consent → halt
  and surface the compliance risk to a human; do not ship a
  non-compliant messaging default.

## Supporting Files

- [references/notification-webhook-sheet.md](references/notification-webhook-sheet.md)
  — channel/default matrix, digest-vs-realtime decision guide, collapse/
  dedup patterns, and the webhook delivery-log field list.
- `evals/evals.json` — behavior cases including notification noise
  control, the opt-out-integrity refusal, and the webhook delivery-log/
  replay surface.
- `evals/trigger-evals.json` — discrimination against `api-event-architect`
  (THE contract seam), `edge-state-ux-designer`, and `observability-operator`.