Webhooks & Event Subscriptions UI in Figma

Quick answer

Webhooks push event notifications to a URL your app controls—usually under Developer → Webhooks, Integrations → Event subscriptions, or Organization → Notifications. Design an endpoint list with URL, subscribed events, status (active/paused/failing), and last delivery; a create flow with URL validation, event multi-select, optional filters, and a one-time signing secret; plus a delivery log with HTTP status, payload preview, retry, and disable-on-failure. Pair with API keys for auth to your API, but keep webhook secrets separate. Log deliveries to audit activity when security-relevant. Start from the Figma guides hub and use Dev Mode handoff for payload schema annotations.

Who this is for

Product designers building developer settings for SaaS platforms, payment processors, and automation tools.
Design system teams distinguishing webhook UI from REST API docs and consumer notification preferences.
Engineers implementing HMAC verification, idempotent retries, dead-letter queues, and endpoint health checks.

Webhooks vs polling vs in-app notifications

Pattern	How it works	Best for	UI home
Webhook (push)	Server POSTs to your URL on events	Real-time sync, automation	Developer → Webhooks
Polling	Client calls API on interval	Simple integrations, no public URL	API docs only
In-app notifications	Bell icon, email, SMS	Human-readable alerts	Notification preferences
SSE / WebSocket	Persistent connection	Live dashboards	Separate real-time docs

Verdict: webhooks belong in developer settings, not beside consumer email toggles. Users expect webhook failures to show HTTP status codes and retry actions, not marketing copy.

Endpoint list row anatomy

Part	Spec	Notes
Label	User-defined name	”Production orders”, “Staging sync”
URL	Truncated HTTPS URL	Mask query params in display
Events	Chip summary	`order.created +2` with tooltip
Status	Active / Paused / Failing	Failing = N consecutive 4xx/5xx
Last delivery	Relative time + status icon	✓ 200 or ✗ 502
Actions	View log, Edit, Pause, Delete	Delete requires confirm

WebhookEndpointRow
├── Variant: status=active | paused | failing | disabled
├── Variant: environment=production | staging
└── Layers:
    ├── StatusDot
    ├── NameLabel
    ├── UrlTruncated
    ├── EventChipGroup
    ├── LastDeliveryMeta
    ├── FailureBanner (conditional)
    └── ActionMenu

Link View delivery log from each row. When an endpoint is auto-disabled after failures, show a banner with Re-enable and link to troubleshooting docs.

Create webhook flow

Step	UI	Validation
1. Name	Text input	Required, 3–64 chars
2. URL	HTTPS URL input	Must be HTTPS; block localhost in prod
3. Events	Searchable multi-select by category	At least one event
4. Filters (optional)	Resource ID, shop, region	Product-specific
5. Secret reveal	Signing secret + copy	One-time only
6. Test delivery	Send sample payload button	Shows result inline
7. Done	Summary + link to log

Secret reveal screen (same discipline as API token creation):

┌─────────────────────────────────────────────┐
│  Your signing secret                        │
│  Use this to verify webhook signatures.     │
│  ┌─────────────────────────────────────┐    │
│  │ whsec_xxxxxxxxxxxxxxxxxxxxxxxx      │ 📋 │
│  └─────────────────────────────────────┘    │
│  ☐ I have stored this secret securely       │
│  [ Send test event ]  [ Done ]              │
└─────────────────────────────────────────────┘

Offer Send test event before Done so engineers verify the endpoint before going live.

Event picker design

Pattern	Best for
Grouped checkboxes	< 30 events in 5–8 categories
Search + multi-select	Large event catalog
Preset bundles	”All order events”, “All user events”
Subscribe to all	Enterprise only; warn on volume

Event category	Example events	UI note
Orders	`order.created`, `order.paid`	High volume badge
Users	`user.updated`, `user.deleted`	Link to privacy
Billing	`invoice.paid`, `subscription.canceled`	Sensitive; log to audit
Security	`login.suspicious`, `api_key.revoked`	Pair with security activity

Document event names and sample JSON payloads in Dev Mode—engineers implement handlers against exact strings.

Delivery log and retry UI

Column / field	Purpose
Timestamp	UTC with local tooltip
Event type	`order.created`
HTTP status	200, 404, 500, timeout
Duration	ms to first byte
Attempt	1 of 5
Actions	Resend, View payload, View response

Delivery detail drawer:

DeliveryDetail
├── SummaryRow (status, event, endpoint)
├── RequestSection
│   ├── Headers (redact Authorization)
│   └── PayloadJson (collapsible, syntax highlight)
├── ResponseSection
│   ├── StatusCode
│   ├── ResponseBody (truncated)
│   └── ResponseHeaders
└── RetryTimeline (attempt 1 → 2 → 3 with backoff)

Delivery state	UI treatment
Success	Green check; collapsible by default in list
Pending retry	Yellow clock; show next retry time
Failed (exhausted)	Red; offer manual resend
Endpoint disabled	Banner on endpoint row + email to admin

Show exponential backoff in retry timeline: “Retry in 1m, 5m, 30m, 2h, 24h”—designers should spec intervals even if copy is dynamic.

Pause, disable, and failure handling

Action	UX	Engineering note
Pause	Stops new deliveries; queue optional	Reversible instantly
Disable after N failures	Auto-pause + email	Default N = 10–25
Delete endpoint	Confirm modal; irreversible	In-flight deliveries may still complete
Rotate secret	New secret; old valid 24h	Same grace pattern as API key rotation

Failure banner copy: “This endpoint returned 502 for 12 consecutive deliveries. Webhooks are paused until you fix the URL or re-enable.”

Link to Verify signature docs and IP allowlist if your product supports outbound IP listing for firewall rules.

Empty, error, and edge states

State	Copy / UI
Empty list	”No webhooks yet” + Create CTA + link to quickstart
Invalid URL on create	”URL must use HTTPS” inline
Test delivery failed	Show status + response body snippet
Rate limited	”Too many endpoints—contact support or delete unused”
Org policy disabled	”Your admin disabled webhooks”

For high-volume products, show estimated events/day when user selects “Subscribe to all”—prevent accidental bill shock or server overload.

Security settings page layout

Section	Contents
Header	”Webhooks” + docs link
Policy note	”Verify signatures on every request”
Create button	Primary, top-right
Active endpoints	Table or card list
Paused / failing	Section with warning styling
Recent deliveries	Global feed optional for admins

Place under Developer or Integrations in account dashboard—adjacent to API keys, not inside notification preferences.

Handoff checklist

Item	Dev Mode annotation
Signature header name	e.g. `X-Webhook-Signature`
Signature algorithm	HMAC-SHA256
Secret format	Prefix + length
Retry schedule	Intervals and max attempts
Idempotency key header	If supported
Payload schema	Link to OpenAPI or JSON sample per event
Timeout	Seconds before attempt marked failed
IP egress list	If published for allowlisting
a11y	Status icons have text labels; JSON viewer keyboard navigable

For PCI or PII events, annotate which payload fields must be redacted in logs displayed to non-admin users.

Common mistakes

Mistake	Why it hurts	Fix
Webhooks mixed with email toggles	Users disable “order emails” and break integrations	Separate developer page
No test delivery on create	Broken URLs discovered in production	Inline test step
Showing full secret after setup	Screenshot leaks	One-time reveal only
Delivery log without response body	Engineers can’t debug 400 errors	Show truncated response
No auto-pause on failures	Infinite retry hammers customer server	Disable after N failures
Event names not searchable	Wrong subscriptions	Search + categories
Missing manual resend	Stuck events after fix	Resend button on failed row
HTTP URLs allowed in prod	MITM risk	HTTPS-only validation

Recommended workflow

Inventory events with API team—group for picker UI.
Design endpoint list row with status, events, last delivery.
Build create wizard through secret reveal and test delivery.
Design delivery log with payload/response drawers and retry timeline.
Add pause, auto-disable, and secret rotation flows.
Wire security events to audit log.
Separate from consumer notifications in information architecture.
Prototype failing endpoint and re-enable flow.

FAQ

Webhooks vs API keys—which does my integration need?

API keys let your app call the platform’s API. Webhooks let the platform call your server when something happens. Most integrations need both.

Should we show full payload JSON in the UI?

Yes for admins and developers, with truncation for large payloads. Redact tokens, card numbers, and passwords in displayed JSON.

How long should delivery logs be retained?

Common ranges: 7–30 days for self-serve; longer for enterprise. Show retention policy in log footer.

Support multiple URLs per event type?

Yes—many products allow several endpoints with different event subscriptions. List view should scale to 10–50 endpoints per org.

Webhook signing vs mTLS?

Signing secret is the default UX. mTLS is enterprise-only—separate toggle, not the default create flow.

Next steps

Design API keys and personal access tokens UI in Figma — programmatic auth paired with webhook receivers
Design audit log and security activity UI in Figma — webhook disabled and security event deliveries
Design notification preferences and communication settings UI in Figma — human alerts, not developer push
Figma Dev Mode for designers: handoff checklist — payload schemas and header names
Best Figma dev handoff plugins (Inspect, tokens, code) — if pairing with OpenAPI documentation

Designing webhooks and event subscriptions UI in Figma: endpoints, secrets, retries, and delivery logs