Webhooks
Benachrichtigen Sie ein anderes System, wenn ein Beitrag von Sofia online geht oder fehlschlägt: signierte Webhooks per API registriert, mit Wiederholungen.
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.publishedundpost.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}/testsendet ein Ereigniswebhook.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-Signaturehat den Wertt=<unix time>,v1=<hex>, wobeiv1der 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.