Social-Vendor-Webhooks (Zernio & Outstand)
Zernio (Werbung, Inbox) und Outstand (Publishing, Community) melden Ereignisse per Webhook ans Cockpit. Das ersetzt Polling an den wichtigsten Stellen; Cron-Jobs bleiben als Fallback.
Was
| Quelle | Event | Cockpit-Reaktion |
|---|---|---|
| Zernio | ad.review.approved, ad.review.rejected | Boost-Status am Post aktualisiert (Abgelehnt (Meta) bzw. Pausiert/Aktiv), Glocke an die Person, die den Boost ausgelöst hat (Fallback: Social-Empfängerkreis des Centers). Bei Ablehnung zusätzlich GET /v1/ads/{adId}/review für Meta-Texte und ausgeschlossene Platzierungen im Panel Beitrags-Bewerbung |
| Zernio | account.ads.sync_failed | Hinweis-Banner auf Social → Reporting und Glocke an die Key-Account-Manager des Centers (einmal pro Störung) |
| Zernio | account.ads.sync_recovered | Hinweis wird entfernt |
| Outstand | message.received | Glocke „Neue Instagram-/Facebook-Nachricht“ → Social → Community → Instagram-Nachrichten (pro Center und Gespräch entprellt, 60 Sekunden) |
| Outstand | message.failed | Glocke „Nachricht nicht zugestellt“ mit Fehlergrund |
| Outstand | conversation.started | Quittiert; die erste Nachricht löst die Glocke aus |
| Outstand | comment.received | wie bisher; zusätzlich Instagram Live (isLive) und Kommentare ohne Outstand-Post (Zuordnung über das Social-Konto), Duplikate werden pro Konto und Kommentar verworfen |
| Outstand | post.published, post.error, account.token_expired | unverändert |
Warum
- Der Boost-Review dauerte bisher bis zu 5 Minuten Polling im Request. Mit Webhook reicht ein kurzer Poll (45 Sekunden); das Ergebnis kommt als Ereignis.
- Direktnachrichten wurden bisher quittiert, aber nicht ausgewertet.
- Zernio meldet stockende Werbe-Syncs aktiv; ohne Hinweis wirkten die KPIs still veraltet.
- Webhooks ohne Signatur-Secret waren in Production möglich (offener POST-Trigger). Jetzt fail-closed.
Wer ist betroffen
Redaktion/Center-Betrieb (Glocke, Hinweis-Banner), Key-Account-Manager (Sync-Störung), IT/Betrieb (Secrets, Webhook-Einrichtung).
Wo
| Zernio-Webhook-URL | https://dashboard.cockpit-os.de/api/webhooks/zernio |
| Outstand-Webhook-URL | https://dashboard.cockpit-os.de/api/webhooks/outstand |
| Boost-Status | Social → Post bearbeiten → Beitrags-Bewerbung |
| Sync-Hinweis | Social → Reporting (oben) |
| DM-Glocke | öffnet Social → Community mit Reiter Instagram-Nachrichten |
Absicherung (Betrieb)
| Quelle | Header | Prüfung |
|---|---|---|
| Zernio | X-Zernio-Signature (Alias X-Late-Signature) | HMAC-SHA256 des Raw-Bodys, Hex, Schlüssel ZERNIO_WEBHOOK_SECRET |
| Outstand | X-Outstand-Signature: sha256=<hex> | HMAC-SHA256 des Raw-Bodys, Schlüssel OUTSTAND_WEBHOOK_SECRET |
- Production ohne Secret: beide Endpunkte antworten
401(fail-closed). Lokal/Test ohne Secret sind unsignierte Requests erlaubt. - Vor dem Deploy:
OUTSTAND_WEBHOOK_SECRETundZERNIO_WEBHOOK_SECRETim Render-Dashboard setzen (sync: false, nicht im Repo). Das Outstand-Secret muss mit dem in Outstand hinterlegten Signing Secret übereinstimmen, sonst scheitern auchpost.published-Webhooks. - Zernio: Zernio erzeugt kein Secret. Beim Anlegen des Webhooks (
POST https://zernio.com/api/v1/webhooks/settings) dasselbe Secret im Feldsecretmitgeben. Events:ad.review.approved,ad.review.rejected,account.ads.sync_failed,account.ads.sync_recovered. DanachPOST /v1/webhooks/testauslösen (webhook.test→200). Die Ads-Events brauchen das Ads-Add-on im Zernio-Konto. - Outstand: In den Webhook-Einstellungen zusätzlich
message.received,message.failed,conversation.startedaktivieren. DM-Events gibt es nur für Konten, die mit Messaging-Rechten verbunden wurden (siehe Outstand-Doku „Enable Direct Messages“). - Zustellung: Zernio liefert mindestens einmal (bis zu 7 Versuche) und erwartet
2xxbinnen 5 Sekunden. Das Cockpit dedupliziert über die Event-ID (Redis, 48 Stunden) und arbeitet zustandsbasiert idempotent.
Fallback ohne Webhook
- Boost: Der tägliche Cron
zernio-ads-sync(erster Batch) prüft Boosts, die seit über 30 Minuten ohne Review-Ergebnis sind, direkt bei Zernio (reconcileStalePaidPromotions). OhneZERNIO_WEBHOOK_SECRETbleibt der lange Poll (Default 5 Minuten) aktiv. - Kommentare/Posts: wie bisher Cron
social-comment-sync(alle 30 Minuten). - Hinweis-Banner: Zustand liegt in Redis (30 Tage). Geht Redis verloren, verschwindet der Banner; die Glocke bleibt als Nachweis.
Vendor-Changelog-Watchdog (Zernio)
Cron POST /api/cron/zernio-changelog-watch (GitHub Action zernio-changelog-watch.yml, täglich 06:00 UTC) liest die öffentliche API GET https://zernio.com/api/v1/changelog?impact=action_required, vergleicht mit der zuletzt gesehenen Eintrags-ID (Redis) und liefert neue Einträge im Cron-Ergebnis. Betrifft ein Eintrag Endpunkte, die das Cockpit nutzt (Ads, Webhooks, Inbox, Accounts, Posts, Analytics), erhalten SUPER_ADMINs eine Glocke. Der erste Lauf setzt nur die Baseline. GET auf denselben Pfad (mit CRON_SECRET) zeigt den gemerkten Stand. Outstand bietet keine öffentliche Changelog-API — dort manuell in der Outstand-Doku prüfen.
So testen
- Secrets in Render setzen, Deploy abwarten.
- Zernio:
POST /v1/webhooks/testmit der Webhook-ID → AntwortTest webhook sent successfully; im Zernio-Dashboard unter Webhook-Logs Status200. - Outstand: im Outstand-Dashboard „Send test“ →
{ "success": true, "message": "Webhook OK" }; ohne korrekte Signatur401. - Boost auf einem Live-Post auslösen; nach Meta-Review erscheint Status und Glocke.
- Eine DM an das verbundene Instagram-Konto senden → Glocke „Neue Instagram-Nachricht“.
Tenant-Routing (profiles[].externalId)
Zernio liefert auf vielen Events ein Top-Level-Feld profiles mit externalId (euer Mandanten-/Center-Schlüssel). Das Cockpit setzt beim Inbox-Link externalId = Cockpit-centerId auf dem Zernio-Profil und wertet Webhooks damit vor der bisherigen Account-Heuristik aus.
Details, Backfill und Grenzen (Portfolio-Ads): Zernio Profiles — externalId.
Code
apps/dashboard/src/lib/integration/: zernio-webhook-auth.ts, zernio-webhook-events.ts, zernio-webhook-handler.ts, zernio-webhook-tenant-routing.ts, zernio-profiles-client.ts, zernio-ad-review.ts, zernio-ads-sync-alerts.ts, zernio-boost-reconcile.ts, zernio-changelog-watch.ts, outstand-webhook-auth.ts, social-outstand-dm-webhook.ts, social-dm-webhook-handler.ts, social-outstand-comment-webhook.ts, webhook-auth-policy.ts.
Tests: pnpm test:ci (u. a. vendor-webhook-auth.test.ts, zernio-webhook-events.test.ts, zernio-webhook-tenant-routing.test.ts, zernio-ad-review.test.ts, social-outstand-dm-webhook.test.ts).
Siehe auch: Social-Media-Freigabe · Social unter Cockpit · Roadmap Paid Social · Cron-Setup: docs/CRON-SETUP.md.
Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/social-vendor-webhooks