Webhook auth
Configure inbound webhook delivery for an app — choose header or bearer auth, secure the secret, and test-fire the webhook from the dashboard.
If you don’t want to poll PrivacyFlow for inbound messages, configure PrivacyFlow to POST them to your webhook URL instead. The Webhook Auth Wizard configures the credential and the app’s delivery setting in three steps. The credential type you choose here is the same type the public API recognizes for authentication — see Authentication and Credentials.
Webhook delivery vs polling
Webhook delivery pushes messages to your endpoint the moment they arrive — no idle polling, no budget burn. Your webhook receiver still authenticates to PrivacyFlow’s public API with the same credential for sends and the occasional verify.
Note
The “delivery type” of an app is a per-app setting: poll, webhook, or all. You can run both modes in parallel if you want redundancy. The choice lives in the app’s settings modal, not in the wizard.
Open the Webhook Auth Wizard
- Sign in to the dashboard.
- Open Apps → choose the app you want to receive webhooks for.
- Open Webhook Auth (either from the app’s settings or the Apps list row action).
- The wizard opens to step 1.
Step 1 — Choose Authentication Method
Two options:
| Option | Credential type created | Header the receiver must accept |
|---|---|---|
| Header | webhook-header | X-Webhook-Token: <key> |
| Bearer | webhook-bearer | Authorization: Bearer <key> |
Warning
Screenshot placeholder — Step 1: two large cards for Header and Bearer with a description under each.
Pick Header if your receiver is a custom service that prefers a dedicated header (some n8n webhook auth schemes, some internal HTTP gateways). Pick Bearer if your receiver speaks OAuth-style Bearer tokens natively (most modern webhook libraries).
Step 2 — Secure Your Secret
Generate a new secret or paste your own. The dashboard offers a Generate button that produces a pf_live_… string. You can also paste an existing key if you’re migrating from a poll credential to a webhook credential using the same secret.
Warning
Screenshot placeholder — Step 2: a Generate button and a paste field, with the secret masked and a Show/Hide toggle.
Save it. The dashboard shows the secret once on this step — copy it. The webhook receiver needs to read this exact value from the chosen header on every inbound POST.
Step 3 — Configure Webhook URL
Enter the HTTPS URL of your webhook receiver. The dashboard will POST inbound message payloads to this URL with the credential’s header set.
Warning
Screenshot placeholder — Step 3: URL field with HTTPS hint and a step indicator showing “Configure Webhook URL”.
After saving, the wizard sets the app’s deliveryType (to webhook if it was poll, or leaves it as all if you want both) and writes the credential. The credential’s appIds[] is set to the app you started from.
Test-fire the webhook
The dashboard has a Test Webhook button (in the app’s settings or the Webhook Auth modal). Clicking it POSTs a synthetic payload to your configured URL with event: "webhook.test" and the credential’s auth header set — useful for verifying your receiver accepts the auth scheme before any real messages flow.
The test request is sent from the browser, not through the backend proxy, so the request originates from the operator’s IP, not the dashboard server’s. Plan your receiver’s CORS / IP allowlist accordingly (or treat webhook.test differently from real message events).
Tip
Set your receiver to log the incoming headers on the test event. You’ll see exactly which header (X-Webhook-Token or Authorization) and which secret the dashboard is sending, so you can verify your receiver is reading them before processing real traffic.
Delivery type: poll, webhook, or all
The app’s deliveryType controls how PrivacyFlow handles inbound messages:
| Delivery type | Behavior |
|---|---|
poll | Messages land in the poll:{appId} queue. You fetch them with GET /api/v1/messages/poll. |
webhook | Messages POST to your webhook URL. The poll:{appId} queue is not populated. |
all | Both — messages go to your webhook AND the poll queue. Useful for redundancy or gradual migration. |
Change delivery type in the app’s Settings modal, not from the Webhook Auth Wizard. The wizard only configures auth; the app’s settings modal controls where messages actually flow.
Mapping back to the public API
The credential the wizard creates is a normal PrivacyFlow credential — it shows up in the Credentials section with the webhook-bearer or webhook-header type badge. The same secret authenticates to the public API for sending or polling (a webhook-bearer credential can call POST /api/v1/messages/send — the type only restricts which header you may send, not which endpoints you may call).
Warning
The receiver’s secret and the sender’s credential secret must match. If you rotate the credential (via Replace), the receiver’s expected secret changes too — update the receiver before, or in lockstep with, the rotation to avoid missed deliveries.
Underlying API calls
| UI action | API route |
|---|---|
| Open the Webhook Auth Wizard from an app’s settings | UI-only (loads Alpine.js form) |
| Wizard step 3 → “Configure Webhook URL” → Save | POST /dashboard/api/dashboard/apps/update with appId, webhookUrl, webhookAuthType, webhookAuthSecret, optional webhookAuthHeaderName |
| Manual “Test Webhook” button | Direct browser fetch to your webhook URL with event: "webhook.test" — bypasses the dashboard proxy, originates from the operator’s IP |
| Change delivery type (poll / webhook / all) | POST /dashboard/api/dashboard/apps/update with deliveryType |
The wizard is a single-page form that issues one POST /dashboard/api/dashboard/apps/update call on save. See apps for the full request shape and the account API reference for the route.