Webhooks

Ein Webhook ist ein HTTP-Aufruf, den Sofia auslöst, wenn ein Beitrag online geht oder fehlschlägt. Nutzen Sie ihn, um den Inhalt in eine Tabelle zu übernehmen, ein Messaging-Tool zu benachrichtigen oder ein Szenario in Zapier oder n8n zu starten.

Einen hinzufügen

• 1. Geben Sie ihm eine Adresse. Eine öffentliche https-Adresse, an die Sofia das Ereignis sendet.
• 2. Wählen Sie die Ereignisse. post.published und post.failed.
• 3. Registrieren Sie ihn. POST /v1/webhooks: Das Signaturgeheimnis (whsec_…) wird nur in dieser Antwort angezeigt.
• 4. Senden Sie einen Test. POST /v1/webhooks/{id}/test sendet ein Ereignis webhook.test, signiert wie die anderen.

Die vollständige Anfrage ist im Tab API beschrieben: Einen Webhook registrieren. Nur die Beiträge, die von Ihrer Anwendung erstellt wurden, werden gemeldet.

Den Empfänger bauen

Senden Sie immer zuerst einen Test und bewahren Sie den empfangenen Body auf: Er ist der Vertrag, verlässlicher als jede Beschreibung. Sofia sendet jedes Ereignis per POST im JSON-Format { id, type, createdAt, data }, mit den Headern Sofia-Event-Id, Sofia-Event-Type und Sofia-Signature.

• Prüfen Sie die Signatur. Sofia-Signature hat den Wert t=<unix time>,v1=<hex>, wobei v1 der HMAC-SHA256 von <t>.<raw body> mit Ihrem Geheimnis ist. Berechnen Sie ihn über den rohen Body und lehnen Sie einen alten Zeitstempel ab.
• Antworten Sie schnell mit `2xx`, und erledigen Sie die Arbeit danach: Ein langsamer Endpunkt ist von einem ausgefallenen nicht zu unterscheiden.
• Seien Sie idempotent. Dasselbe Ereignis kann zweimal ankommen: Entdoppeln Sie über Sofia-Event-Id.

Wenn ein Webhook nicht mehr auslöst

Die Adresse ist nicht erreichbar

Sofia ruft von ihren Servern aus auf: Die Adresse muss eine öffentliche https-Adresse sein. Einer Weiterleitung wird nie gefolgt, und 10 Sekunden ohne Antwort gelten als Fehlschlag.

Die Adresse liefert einen Fehler

Jede andere Antwort als 2xx löst einen neuen Versuch nach 1 Minute, 5 Minuten, 30 Minuten und 2 Stunden aus, bis zu 5 Versuche. Sehen Sie zuerst in Ihre eigenen Protokolle und reproduzieren Sie dann mit POST /v1/webhooks/{id}/test.

Der Beitrag wurde nicht von Ihrer Anwendung erstellt

Ein Webhook meldet nur die Beiträge, die von Ihrer Anwendung erstellt wurden; ein in der Oberfläche erstellter Beitrag löst ihn nicht aus.

Siehe auch

Ein Webhook sagt, wann Sofia gehandelt hat. Damit Sofia handelt, nutzen Sie Sofia API, die CLI sofia oder den MCP-Server (Tabs API und Agents) oder Integrationen von Drittanbietern.