feat: outbound webhooks for event/photo lifecycle (#327)
PicPeak POSTs lifecycle notifications to admin-configured URLs. Each delivery is signed HMAC-SHA256 in the X-PicPeak-Signature header. Verified end-to-end: 1/1 Playwright spec, 8/8 backend integration tests, full UI click-through via Chrome DevTools. Schema (migration 082) - webhooks: id, name, url, secret (plaintext — required to compute HMAC for every outbound POST), secret_preview, events[], active, filter, template, created_by, timestamps, last_success_at/last_failure_at. - webhook_deliveries: webhook_id (FK CASCADE), event_type, payload, attempt_count, status (pending|success|failed), response_status, response_body (truncated to 1KB), latency_ms, next_retry_at, last_error, created_at, completed_at. Composite index (status, next_retry_at) serves the worker's hot-path query. Service + worker - webhookService.fire(eventType, data) — non-throwing entry point used by lifecycle hooks. Looks up active webhooks subscribed to the event and applies their per-webhook filter (dot-path equality predicate) before enqueueing one webhook_deliveries row per match. Filter and template logic ship in this commit; admin surfaces in the follow-up. - webhookDeliveryWorker — setInterval(5s) poller; fetches up to 5 pending rows; per delivery: re-validates URL via networkValidation (DNS-rebinding mitigation, opt-out via WEBHOOK_ALLOW_PRIVATE_URLS), signs body with HMAC-SHA256, POSTs with 10s timeout, records outcome. Backoff schedule: 1m → 5m → 30m → 2h → 12h, max 5 attempts. Response body truncated to 1KB before storage. If a webhook has a template, the rendered string replaces the JSON envelope as the request body (signature is computed over the bytes actually sent). Lifecycle wiring - adminEvents.js POST /events → event.created (+ event.published when not draft); POST /:id/publish → event.published. - routes/events.js (legacy public POST) → event.created + event.published. - routes/v1/events.js (#322 API) → event.created + event.published on create, photo.uploaded on photo POST. - archiveService.archiveEvent() → event.archived. Per-photo photo.deleted intentionally NOT fired during cascade — receivers infer from event.archived to avoid flooding (issue spec). - expirationChecker.handleExpiredEvent() → event.expired BEFORE the cascading archive (so receivers see expired→archived in order). - adminPhotos.js — photo.uploaded on each batch row, photo.deleted on single + bulk delete. - photoProcessor.js — photo.uploaded for guest uploads + auto-import (covers all entry paths). - fileWatcher.js — photo.uploaded on add, photo.deleted on unlink (local mode only). Admin endpoints (mirrors adminApiTokens.js pattern) - /api/admin/webhooks: GET list, POST create (returns plaintext secret exactly once), GET :id, PUT :id, DELETE :id, POST :id/test (synthetic fire), GET :id/deliveries (paginated, filter by status), GET :id/deliveries/:deliveryId, POST :id/deliveries/:deliveryId/replay. Frontend - Settings → Webhooks tab (mirrors API Tokens layout): name + URL + event checkboxes + "Advanced" expander for filter (JSON) and template. Plaintext secret shown once on creation with a Copy button. Active/ Disabled toggle button per row. - /admin/webhooks/:id/deliveries — operational debug surface. Table with timestamp/event/status/attempts/HTTP/latency. Status filter chips (all/pending/success/failed). Row click → slide-over with payload + signature + response body. Replay button on failed rows. Send-test-event dialog. Auto-refresh every 10s. Dev infrastructure - dev/webhook-receiver/ — tiny node:alpine HTTP server (~100 LOC) that records every POST to an in-memory ring buffer. Exposes GET /requests for the E2E spec to assert deliveries landed with the right HMAC. Sibling pattern to MinIO. Reachable from the backend at http://webhook-receiver:8888 inside the picpeak network. Tests - backend/__tests__/integration/webhookDelivery.test.js (8/8) — signature verification, headers, retry/backoff, max-attempts → failed, response truncation, disabled-mid-flight, SSRF block, start/stop idempotency. - tests/e2e/webhooks-roundtrip.spec.ts (1/1) — create webhook → trigger event.published → assert receiver got POST with valid HMAC → visit deliveries page → row visible with status=success → API test event → API replay → disable webhook → assert no new delivery. Docs - README §"Webhooks" — event catalog, payload shape, HMAC verification in Node + Python + bash, retry semantics, SSRF protection. - .env.example — WEBHOOK_ALLOW_PRIVATE_URLS, WEBHOOK_DELIVERY_INTERVAL_MS, WEBHOOK_DELIVERY_CONCURRENCY, WEBHOOK_HTTP_TIMEOUT_MS, WEBHOOK_MAX_ATTEMPTS. Out of scope for v1 (per issue): webhook templates' code-eval (the ${dot.path} substitution that ships is pure string replacement, no expression engine — see follow-up commit), per-webhook rate limiting beyond the global concurrency cap, synchronous "ask before delete" webhooks. Spanning files - App.tsx pulls in this commit with both the AnalyticsBootstrap (#325 dedup) and the WebhookDeliveriesPage route registration. Splitting via git add -p was forfeit for sanity; the single 92-line diff is honest about both contributions. - adminEvents.js diff bundles the webhook fires AND the allow_presigned_download field plumbing (#328 follow-up). Same reasoning. - The new webhookService/Worker/adminWebhooks files include the filter and template logic from the follow-up — they were authored in one pass; splitting them post-hoc would have produced fragile partial files. The follow-up commit covers the migration and the UI for these.
This commit is contained in:
Paul Nothaft
@@ -16,3 +16,4 @@ export { StylingTab } from './tabs/StylingTab';
|
||||
export { SEOTab } from './tabs/SEOTab';
|
||||
export { ThumbnailsTab } from './tabs/ThumbnailsTab';
|
||||
export { ApiTokensTab } from './tabs/ApiTokensTab';
|
||||
export { WebhooksTab } from './tabs/WebhooksTab';
|
||||
|
||||
@@ -0,0 +1,354 @@
|
||||
import React, { useState } from 'react';
|
||||
import { useTranslation } from 'react-i18next';
|
||||
import { Link } from 'react-router-dom';
|
||||
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
|
||||
import { toast } from 'react-toastify';
|
||||
import { Webhook as WebhookIcon, Trash2, Copy, AlertTriangle, Activity, CheckCircle2, XCircle } from 'lucide-react';
|
||||
import { Button, Card, Input, Loading } from '../../../components/common';
|
||||
import { api } from '../../../config/api';
|
||||
|
||||
const WEBHOOK_EVENT_TYPES = [
|
||||
'event.created',
|
||||
'event.published',
|
||||
'event.archived',
|
||||
'event.expired',
|
||||
'photo.uploaded',
|
||||
'photo.deleted',
|
||||
] as const;
|
||||
type WebhookEventType = typeof WEBHOOK_EVENT_TYPES[number];
|
||||
|
||||
interface WebhookRow {
|
||||
id: number;
|
||||
name: string;
|
||||
url: string;
|
||||
events: WebhookEventType[];
|
||||
active: boolean;
|
||||
secret_preview: string | null;
|
||||
created_at: string;
|
||||
updated_at: string;
|
||||
last_success_at: string | null;
|
||||
last_failure_at: string | null;
|
||||
owner_username: string | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Settings → Webhooks tab (#327). Mirrors the API Tokens tab pattern:
|
||||
* the signing secret is returned exactly once on creation and never
|
||||
* recoverable. Per-webhook delivery history lives on the dedicated
|
||||
* /admin/webhooks/:id/deliveries page (link in the table).
|
||||
*/
|
||||
export const WebhooksTab: React.FC = () => {
|
||||
const { t } = useTranslation();
|
||||
const queryClient = useQueryClient();
|
||||
const [name, setName] = useState('');
|
||||
const [url, setUrl] = useState('');
|
||||
const [events, setEvents] = useState<WebhookEventType[]>(['event.published']);
|
||||
const [filterText, setFilterText] = useState('{}');
|
||||
const [template, setTemplate] = useState('');
|
||||
const [showAdvanced, setShowAdvanced] = useState(false);
|
||||
const [justCreatedSecret, setJustCreatedSecret] = useState<string | null>(null);
|
||||
const [filterError, setFilterError] = useState<string | null>(null);
|
||||
|
||||
const { data: webhooks, isLoading } = useQuery({
|
||||
queryKey: ['admin-webhooks'],
|
||||
queryFn: async () => {
|
||||
const res = await api.get<WebhookRow[]>('/admin/webhooks');
|
||||
return res.data;
|
||||
},
|
||||
});
|
||||
|
||||
const createMutation = useMutation({
|
||||
mutationFn: async () => {
|
||||
let parsedFilter: Record<string, unknown> = {};
|
||||
const trimmed = filterText.trim();
|
||||
if (trimmed && trimmed !== '{}') {
|
||||
try {
|
||||
parsedFilter = JSON.parse(trimmed);
|
||||
} catch {
|
||||
setFilterError('Filter must be valid JSON');
|
||||
throw new Error('Invalid filter JSON');
|
||||
}
|
||||
}
|
||||
setFilterError(null);
|
||||
const body: Record<string, unknown> = { name, url, events, active: true };
|
||||
if (Object.keys(parsedFilter).length > 0) body.filter = parsedFilter;
|
||||
if (template.trim()) body.template = template;
|
||||
const res = await api.post<{ secret: string }>('/admin/webhooks', body);
|
||||
return res.data.secret;
|
||||
},
|
||||
onSuccess: (secret) => {
|
||||
setJustCreatedSecret(secret);
|
||||
setName('');
|
||||
setUrl('');
|
||||
setEvents(['event.published']);
|
||||
setFilterText('{}');
|
||||
setTemplate('');
|
||||
setShowAdvanced(false);
|
||||
queryClient.invalidateQueries({ queryKey: ['admin-webhooks'] });
|
||||
},
|
||||
onError: (err: any) => {
|
||||
toast.error(err?.response?.data?.errors?.[0]?.msg || err?.response?.data?.error || 'Failed to create webhook');
|
||||
},
|
||||
});
|
||||
|
||||
const toggleActiveMutation = useMutation({
|
||||
mutationFn: async ({ id, active }: { id: number; active: boolean }) =>
|
||||
api.put(`/admin/webhooks/${id}`, { active }),
|
||||
onSuccess: () => queryClient.invalidateQueries({ queryKey: ['admin-webhooks'] }),
|
||||
onError: () => toast.error('Failed to update webhook'),
|
||||
});
|
||||
|
||||
const deleteMutation = useMutation({
|
||||
mutationFn: async (id: number) => api.delete(`/admin/webhooks/${id}`),
|
||||
onSuccess: () => {
|
||||
toast.success('Webhook deleted');
|
||||
queryClient.invalidateQueries({ queryKey: ['admin-webhooks'] });
|
||||
},
|
||||
onError: () => toast.error('Failed to delete webhook'),
|
||||
});
|
||||
|
||||
const toggleEvent = (e: WebhookEventType) => {
|
||||
setEvents((prev) => (prev.includes(e) ? prev.filter((x) => x !== e) : [...prev, e]));
|
||||
};
|
||||
|
||||
if (isLoading) {
|
||||
return (
|
||||
<div className="flex items-center justify-center min-h-[200px]">
|
||||
<Loading size="lg" />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="space-y-6">
|
||||
<Card padding="md">
|
||||
<h2 className="text-lg font-semibold text-neutral-900 dark:text-neutral-100 mb-2 flex items-center gap-2">
|
||||
<WebhookIcon className="w-5 h-5" />
|
||||
{t('settings.webhooks.title', 'Webhooks')}
|
||||
</h2>
|
||||
<p className="text-sm text-neutral-600 dark:text-neutral-400 mb-4">
|
||||
{t('settings.webhooks.subtitle', 'POST event notifications to your URL the moment something happens — gallery published, photo uploaded, event archived, etc. Signed with HMAC-SHA256 in the X-PicPeak-Signature header.')}
|
||||
</p>
|
||||
|
||||
{justCreatedSecret && (
|
||||
<div className="rounded-lg border border-amber-300 bg-amber-50 dark:bg-amber-900/20 p-4 mb-4">
|
||||
<div className="flex items-start gap-3">
|
||||
<AlertTriangle className="w-5 h-5 text-amber-600 dark:text-amber-400 flex-shrink-0 mt-0.5" />
|
||||
<div className="flex-1 min-w-0">
|
||||
<p className="text-sm font-medium text-amber-900 dark:text-amber-200 mb-1">
|
||||
{t('settings.webhooks.copyNow', 'Copy this signing secret now — it will not be shown again.')}
|
||||
</p>
|
||||
<div className="flex items-center gap-2">
|
||||
<code className="block flex-1 min-w-0 px-3 py-2 bg-white dark:bg-neutral-900 border border-amber-300 dark:border-amber-700 rounded text-xs font-mono break-all">
|
||||
{justCreatedSecret}
|
||||
</code>
|
||||
<Button
|
||||
size="sm"
|
||||
variant="outline"
|
||||
leftIcon={<Copy className="w-4 h-4" />}
|
||||
onClick={async () => {
|
||||
try {
|
||||
await navigator.clipboard.writeText(justCreatedSecret);
|
||||
toast.success('Copied');
|
||||
} catch {
|
||||
toast.error('Copy failed');
|
||||
}
|
||||
}}
|
||||
>
|
||||
Copy
|
||||
</Button>
|
||||
<Button size="sm" variant="ghost" onClick={() => setJustCreatedSecret(null)}>
|
||||
Dismiss
|
||||
</Button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
<div className="space-y-3">
|
||||
<div className="grid grid-cols-1 md:grid-cols-2 gap-3">
|
||||
<div>
|
||||
<label className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
|
||||
{t('settings.webhooks.name', 'Name')}
|
||||
</label>
|
||||
<Input value={name} onChange={(e) => setName(e.target.value)} placeholder="e.g. n8n WhatsApp" />
|
||||
</div>
|
||||
<div>
|
||||
<label className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
|
||||
{t('settings.webhooks.url', 'Receiver URL')}
|
||||
</label>
|
||||
<Input value={url} onChange={(e) => setUrl(e.target.value)} placeholder="https://n8n.example.com/webhook/picpeak" />
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<label className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-2">
|
||||
{t('settings.webhooks.events', 'Subscribe to events')}
|
||||
</label>
|
||||
<div className="grid grid-cols-2 sm:grid-cols-3 gap-2">
|
||||
{WEBHOOK_EVENT_TYPES.map((e) => (
|
||||
<label key={e} className="flex items-center gap-2 text-sm text-neutral-700 dark:text-neutral-300">
|
||||
<input
|
||||
type="checkbox"
|
||||
checked={events.includes(e)}
|
||||
onChange={() => toggleEvent(e)}
|
||||
className="w-4 h-4 text-primary-600 rounded focus:ring-primary-500"
|
||||
/>
|
||||
<code className="text-xs">{e}</code>
|
||||
</label>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<button
|
||||
type="button"
|
||||
onClick={() => setShowAdvanced((prev) => !prev)}
|
||||
className="text-sm text-primary-600 dark:text-primary-400 hover:underline self-start"
|
||||
>
|
||||
{showAdvanced ? '− Hide advanced (filter, template)' : '+ Advanced (filter, template)'}
|
||||
</button>
|
||||
|
||||
{showAdvanced && (
|
||||
<div className="space-y-3 border-l-2 border-neutral-200 dark:border-neutral-700 pl-4">
|
||||
<div>
|
||||
<label className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
|
||||
{t('settings.webhooks.filter', 'Filter (JSON, optional)')}
|
||||
</label>
|
||||
<textarea
|
||||
value={filterText}
|
||||
onChange={(e) => { setFilterText(e.target.value); setFilterError(null); }}
|
||||
placeholder='{"data.event.event_type": "wedding"}'
|
||||
rows={3}
|
||||
className="w-full px-3 py-2 border border-neutral-300 dark:border-neutral-700 dark:bg-neutral-800 rounded text-sm font-mono"
|
||||
/>
|
||||
<p className="text-xs text-neutral-500 mt-1">
|
||||
Dot-path → expected value. All keys must match (AND). Use an array for "any of": <code>{'{"type": ["event.published", "event.archived"]}'}</code>
|
||||
</p>
|
||||
{filterError && <p className="text-xs text-red-600 mt-1">{filterError}</p>}
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<label className="block text-sm font-medium text-neutral-700 dark:text-neutral-300 mb-1">
|
||||
{t('settings.webhooks.template', 'Template (optional)')}
|
||||
</label>
|
||||
<textarea
|
||||
value={template}
|
||||
onChange={(e) => setTemplate(e.target.value)}
|
||||
placeholder={'New gallery: ${data.event.event_name} → ${data.event.share_url}'}
|
||||
rows={3}
|
||||
className="w-full px-3 py-2 border border-neutral-300 dark:border-neutral-700 dark:bg-neutral-800 rounded text-sm font-mono"
|
||||
/>
|
||||
<p className="text-xs text-neutral-500 mt-1">
|
||||
Replaces the default JSON envelope as the request body. <code>${'{dot.path}'}</code> substitution from the payload only — no logic, no expressions.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
|
||||
<Button
|
||||
variant="primary"
|
||||
onClick={() => createMutation.mutate()}
|
||||
isLoading={createMutation.isPending}
|
||||
disabled={!name.trim() || !url.trim() || events.length === 0}
|
||||
>
|
||||
{t('settings.webhooks.create', 'Create Webhook')}
|
||||
</Button>
|
||||
</div>
|
||||
</Card>
|
||||
|
||||
<Card padding="md">
|
||||
<h3 className="text-base font-semibold text-neutral-900 dark:text-neutral-100 mb-3">
|
||||
{t('settings.webhooks.existing', 'Existing webhooks')}
|
||||
</h3>
|
||||
{webhooks && webhooks.length > 0 ? (
|
||||
<div className="overflow-x-auto">
|
||||
<table className="w-full text-sm">
|
||||
<thead>
|
||||
<tr className="text-left text-neutral-500 dark:text-neutral-400 border-b border-neutral-200 dark:border-neutral-700">
|
||||
<th className="py-2 pr-3">Name</th>
|
||||
<th className="py-2 pr-3">URL</th>
|
||||
<th className="py-2 pr-3">Events</th>
|
||||
<th className="py-2 pr-3">Last delivery</th>
|
||||
<th className="py-2 pr-3">Status</th>
|
||||
<th className="py-2 text-right">Actions</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{webhooks.map((wh) => {
|
||||
const lastSuccess = wh.last_success_at ? new Date(wh.last_success_at) : null;
|
||||
const lastFailure = wh.last_failure_at ? new Date(wh.last_failure_at) : null;
|
||||
const lastEither = lastFailure && (!lastSuccess || lastFailure > lastSuccess) ? 'failure' : (lastSuccess ? 'success' : 'none');
|
||||
return (
|
||||
<tr key={wh.id} className="border-b border-neutral-100 dark:border-neutral-800 last:border-0 align-top">
|
||||
<td className="py-3 pr-3 font-medium">{wh.name}</td>
|
||||
<td className="py-3 pr-3 text-xs font-mono text-neutral-600 dark:text-neutral-400 max-w-xs truncate" title={wh.url}>{wh.url}</td>
|
||||
<td className="py-3 pr-3 text-xs text-neutral-500">
|
||||
{Array.isArray(wh.events) ? wh.events.length : 0} subscribed
|
||||
</td>
|
||||
<td className="py-3 pr-3 text-xs text-neutral-500">
|
||||
{lastEither === 'success' && lastSuccess && (
|
||||
<span className="flex items-center gap-1 text-green-600 dark:text-green-400">
|
||||
<CheckCircle2 className="w-3.5 h-3.5" />
|
||||
{lastSuccess.toLocaleString()}
|
||||
</span>
|
||||
)}
|
||||
{lastEither === 'failure' && lastFailure && (
|
||||
<span className="flex items-center gap-1 text-red-600 dark:text-red-400">
|
||||
<XCircle className="w-3.5 h-3.5" />
|
||||
{lastFailure.toLocaleString()}
|
||||
</span>
|
||||
)}
|
||||
{lastEither === 'none' && <span className="text-neutral-400">—</span>}
|
||||
</td>
|
||||
<td className="py-3 pr-3">
|
||||
<button
|
||||
onClick={() => toggleActiveMutation.mutate({ id: wh.id, active: !wh.active })}
|
||||
className={`text-xs px-2 py-0.5 rounded ${
|
||||
wh.active
|
||||
? 'bg-green-100 dark:bg-green-900/30 text-green-700 dark:text-green-300'
|
||||
: 'bg-neutral-200 dark:bg-neutral-700 text-neutral-600 dark:text-neutral-400'
|
||||
}`}
|
||||
title={wh.active ? 'Click to disable' : 'Click to enable'}
|
||||
>
|
||||
{wh.active ? 'Active' : 'Disabled'}
|
||||
</button>
|
||||
</td>
|
||||
<td className="py-3 text-right">
|
||||
<div className="flex items-center justify-end gap-1">
|
||||
<Link
|
||||
to={`/admin/webhooks/${wh.id}/deliveries`}
|
||||
className="inline-flex items-center gap-1 px-2 py-1 text-xs text-neutral-600 dark:text-neutral-400 hover:text-neutral-900 dark:hover:text-neutral-100"
|
||||
>
|
||||
<Activity className="w-3.5 h-3.5" />
|
||||
Deliveries
|
||||
</Link>
|
||||
<Button
|
||||
size="sm"
|
||||
variant="ghost"
|
||||
leftIcon={<Trash2 className="w-4 h-4" />}
|
||||
onClick={() => {
|
||||
if (confirm(`Delete "${wh.name}"? Pending deliveries are also removed.`)) {
|
||||
deleteMutation.mutate(wh.id);
|
||||
}
|
||||
}}
|
||||
>
|
||||
Delete
|
||||
</Button>
|
||||
</div>
|
||||
</td>
|
||||
</tr>
|
||||
);
|
||||
})}
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
) : (
|
||||
<p className="text-sm text-neutral-500 dark:text-neutral-400">
|
||||
{t('settings.webhooks.empty', 'No webhooks yet. Create one above to start receiving event notifications.')}
|
||||
</p>
|
||||
)}
|
||||
</Card>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
Reference in New Issue
Block a user