Zum Hauptinhalt springen

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​

QuelleEventCockpit-Reaktion
Zernioad.review.approved, ad.review.rejectedBoost-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
Zernioaccount.ads.sync_failedHinweis-Banner auf Social → Reporting und Glocke an die Key-Account-Manager des Centers (einmal pro Störung)
Zernioaccount.ads.sync_recoveredHinweis wird entfernt
Outstandmessage.receivedGlocke „Neue Instagram-/Facebook-Nachricht“ → Social → Community → Instagram-Nachrichten (pro Center und Gespräch entprellt, 60 Sekunden)
Outstandmessage.failedGlocke „Nachricht nicht zugestellt“ mit Fehlergrund
Outstandconversation.startedQuittiert; die erste Nachricht löst die Glocke aus
Outstandcomment.receivedwie bisher; zusätzlich Instagram Live (isLive) und Kommentare ohne Outstand-Post (Zuordnung über das Social-Konto), Duplikate werden pro Konto und Kommentar verworfen
Outstandpost.published, post.error, account.token_expiredunverä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-URLhttps://dashboard.cockpit-os.de/api/webhooks/zernio
Outstand-Webhook-URLhttps://dashboard.cockpit-os.de/api/webhooks/outstand
Boost-StatusSocial → Post bearbeiten → Beitrags-Bewerbung
Sync-HinweisSocial → Reporting (oben)
DM-Glockeöffnet Social → Community mit Reiter Instagram-Nachrichten

Absicherung (Betrieb)​

QuelleHeaderPrüfung
ZernioX-Zernio-Signature (Alias X-Late-Signature)HMAC-SHA256 des Raw-Bodys, Hex, Schlüssel ZERNIO_WEBHOOK_SECRET
OutstandX-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_SECRET und ZERNIO_WEBHOOK_SECRET im Render-Dashboard setzen (sync: false, nicht im Repo). Das Outstand-Secret muss mit dem in Outstand hinterlegten Signing Secret übereinstimmen, sonst scheitern auch post.published-Webhooks.
  • Zernio: Zernio erzeugt kein Secret. Beim Anlegen des Webhooks (POST https://zernio.com/api/v1/webhooks/settings) dasselbe Secret im Feld secret mitgeben. Events: ad.review.approved, ad.review.rejected, account.ads.sync_failed, account.ads.sync_recovered. Danach POST /v1/webhooks/test auslö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.started aktivieren. 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 2xx binnen 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). Ohne ZERNIO_WEBHOOK_SECRET bleibt 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​

  1. Secrets in Render setzen, Deploy abwarten.
  2. Zernio: POST /v1/webhooks/test mit der Webhook-ID → Antwort Test webhook sent successfully; im Zernio-Dashboard unter Webhook-Logs Status 200.
  3. Outstand: im Outstand-Dashboard „Send test“ → { "success": true, "message": "Webhook OK" }; ohne korrekte Signatur 401.
  4. Boost auf einem Live-Post auslösen; nach Meta-Review erscheint Status und Glocke.
  5. 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: /developer-guide/social-vendor-webhooks