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).
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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
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).
The channels available and their constraints: in-app center, email
(deliverability, legal opt-out rules), push (permission, platform
limits), and any SMS.
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.
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?".
Legal/compliance constraints on messaging: unsubscribe obligations,
the transactional-vs-marketing distinction, and consent records.
Workflow
End-user notifications
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.
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.
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.
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.
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
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.
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.
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).
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
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.
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
— 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.
