Zustellung und Sicherheit

Ihr System verarbeitet nur Nachrichten mit gültiger Signatur. procuris signiert jede Nachricht an Ihre Zieladresse. Signieren heißt unterschreiben mit einem geheimen Schlüssel, den nur procuris und Ihr System kennen. Fällt Ihr System bis zu drei Tage aus, geht keine Nachricht verloren, weil procuris gescheiterte Nachrichten über gut drei Tage wiederholt. Die Zustellung folgt der offenen Spezifikation Standard Webhooks.

Was ankommt

Jede Nachricht ist eine POST-Anfrage über HTTPS an Ihre Adresse. Der Körper, also der Inhalt der Anfrage, ist JSON (content-type: application/json). Dazu kommen drei Header:

procuris nimmt nur Adressen mit HTTPS an.

Signatur prüfen, Schritt für Schritt

Die Signatur ist ein HMAC-SHA256. Bei diesem verbreiteten Verfahren entsteht aus Nachricht und geheimem Schlüssel eine Prüfsumme. Ohne den Schlüssel lässt sie sich nicht fälschen.

Das Secret steht in procuris unter Einstellungen › Organisation › Webhooks bei der Zieladresse. Den Bereich sieht nur die Person mit der Rolle Inhaber. Er erscheint erst, wenn der Zugang nach Vertragsschluss eingerichtet ist. Bis dahin führt die Zeile Webhooks im Abschnitt Auf Anfrage derselben Seite nur zur Anfrage eines Angebots.

1. Secret lesen. Das Secret hat die Form whsec_<Base64>. Der Teil nach whsec_ ist der Schlüssel in Base64, 32 Byte lang. Jede Zieladresse hat ein eigenes Secret.
2. Körper roh lesen. Nehmen Sie den Körper genau so, wie er ankam, als Bytes, bevor Ihr System ihn als JSON auswertet. Schon ein Leerzeichen mehr nach dem Auswerten und neuen Zusammensetzen macht die Signatur ungültig.
3. Zeichenfolge bilden. webhook-id, Punkt, webhook-timestamp, Punkt, Körper: msg_2KWP….1674087231.{"type":"tender.published",…}.
4. Prüfsumme rechnen. HMAC-SHA256 über diese Zeichenfolge mit dem Schlüssel, Ergebnis in Base64, davor v1,.
5. Vergleichen. Stimmt einer der Einträge in webhook-signature genau überein, ist die Nachricht echt. Vergleichen Sie in konstanter Zeit, damit die Laufzeit nichts über die Signatur verrät.
6. Zeitpunkt prüfen. Liegt webhook-timestamp mehr als 5 Minuten vor oder nach Ihrer Uhrzeit, verwerfen Sie die Nachricht. Die Grenze verhindert, dass jemand eine mitgeschnittene Nachricht später erneut einspielt.

Unvollständige Nachrichten verwerfen Sie ebenfalls. Das gilt, wenn einer der drei Header fehlt oder webhook-timestamp keine ganze Zahl ist. Eine verworfene Nachricht beantworten Sie mit 401 statt mit 2xx, damit procuris sie als gescheitert wertet und nach Plan erneut schickt.

Fertige Bibliotheken

Die offiziellen Bibliotheken von Standard Webhooks ersetzen die sechs Schritte. Sie prüfen Signatur und Zeitpunkt in einem Aufruf und werten mehrere Signaturen im Header aus. Eine eigene Umsetzung muss das beim Secret-Wechsel selbst leisten, sonst lehnt sie in den 24 Stunden Übergang echte Nachrichten ab.

Die Liste stammt aus dem Repository standard-webhooks/standard-webhooks. Die Bibliotheken nehmen das Secret mit whsec_, den rohen Körper und die drei Header.

Antworten

Ihr Endpunkt antwortet innerhalb von 15 Sekunden mit 2xx. Gemeint ist ein Status wie 200 oder 204. Erst dann gilt die Nachricht als zugestellt.

Ihr Empfänger speichert zuerst und verarbeitet danach. Er legt die Nachricht zum Beispiel in eine Warteschlange, also eine Liste, die Ihr System danach der Reihe nach abarbeitet. Ein CRM-Eintrag vor der Antwort kann die 15 Sekunden überschreiten. procuris wertet das als Fehlschlag.

Rückstau hinter einem Proxy. Ein Rückstau baut sich auch gedrosselt in Stunden ab. Ein Proxy ist ein Server, der Anfragen an Ihr System weiterreicht. Antwortet er mit 502, etwa weil der Dienst dahinter neu startet, schickt procuris nur noch eine Nachricht zur Zeit. Bei einer Antwortzeit von einer Sekunde sind das rund 3.600 Nachrichten je Stunde. Ein Rückstau von einigen Tausend Nachrichten ist also in ein bis zwei Stunden abgebaut. Nach zehn gelungenen Zustellungen in Folge schickt procuris wieder bis zu zehn zugleich.

Wenn Ihr System ausfällt

Ein Ausfall von einer Stunde kostet keine Nachricht. procuris versucht eine Nachricht bis zu zehnmal, den letzten Versuch gut drei Tage nach dem ersten. Fällt Ihr System eine Stunde aus, kommt eine Nachricht aus dieser Stunde mit dem dritten, vierten oder fünften Versuch an. Eine Nachricht vom Anfang der Stunde kommt mit dem fünften Versuch, rund 2 Stunden und 35 Minuten nach ihrem ersten. Eine vom Ende der Stunde kommt schon mit dem dritten, gut 5 Minuten nach ihrem ersten.

Nach Plan liegt der letzte Versuch rund 75,6 Stunden nach dem ersten. Jeder Abstand verlängert sich um einen Zufallsanteil von höchstens 10 Prozent, damit Wiederholungen nicht gleichzeitig eintreffen. Vor dem zehnten Versuch sind das bis zu 2,4 Stunden. Verlangt Ihr System mit Retry-After längere Pausen, verschieben sich die Versuche entsprechend. Spätestens 90 Stunden nach dem ersten Versuch ist eine Nachricht zugestellt oder verworfen, Zufallsanteil und Retry-After eingeschlossen.

Bei längeren Störungen greifen drei Regeln:

• Eine einzelne Nachricht scheitert dauerhaft, zum Beispiel weil Ihr System genau diesen Datensatz ablehnt. Nach dem zehnten Versuch verwirft procuris sie. Die Person mit der Rolle Inhaber bekommt einmal am Tag eine Sammelmail mit webhook-id und Ereignis jeder verworfenen Nachricht. Die übrigen Nachrichten laufen weiter.
• 5 Tage lang gelingt keine Zustellung an eine Adresse. procuris stellt die Zustellung dorthin ein und schreibt der Inhaberin. Nach der Antwort 410 stellt procuris die Zustellung ebenfalls ein. Ist Ihr System bereit, wählt die Inhaberin unter Webhooks bei der Zieladresse Zustellung wieder aufnehmen.
• Verpasste Nachrichten nachholen. Die Nachlieferung reicht 7 Tage zurück. Nach einer Störung sendet die Inhaberin unter Webhooks die verpassten Nachrichten dieser 7 Tage erneut, mit ihrer ursprünglichen webhook-id. Ältere Lücken bei tender.* holt nur ein System mit API-Zugang nach, über die API mit updated_since. Ältere search.hit lassen sich nicht nachholen, weil die API keine Passung und keine Suchaufträge kennt.

Ist niemand mit der Rolle Inhaber erreichbar, schreiben Sie an support@procuris.eu. Der Support nimmt die Zustellung dann nach Rückfrage bei Ihrer Organisation wieder auf.

Doppelte Nachrichten

Dieselbe Nachricht kann mehrmals ankommen, etwa wenn Ihre Antwort unterwegs verloren geht. webhook-id bleibt dabei gleich. Speichern Sie jede verarbeitete webhook-id 4 Tage lang und übergehen Sie eine Nachricht, deren webhook-id Sie schon kennen. 4 Tage reichen, weil procuris eine Nachricht spätestens 90 Stunden nach ihrem ersten Versuch zustellt oder verwirft.

Nachgelieferte Nachrichten können älter als 4 Tage sein. Für sie schützt der Vergleich der Zeitpunkte statt der Kennung. Felder aus data.tender übernimmt Ihr System nur, wenn data.tender.lastModified neuer ist als der gespeicherte Stand. data.fit aus search.hit übernimmt es nur, wenn der timestamp der Nachricht neuer ist als der der zuletzt übernommenen Passung, siehe Ereignisse.

Secret wechseln

Die Inhaberin wechselt das Secret selbst, auf zwei Wegen. Unter Einstellungen › Organisation › Webhooks stehen bei jeder Zieladresse Secret erneuern und Secret sofort ersetzen. Den Ausschlag gibt, ob das alte Secret noch 24 Stunden gelten darf.

Secret erneuern

Secret erneuern wechselt das Secret ohne Ausfall. Nehmen Sie diesen Weg für den geplanten Wechsel, zum Beispiel wenn jemand mit Kenntnis des Secrets das Unternehmen verlässt. Die Inhaberin gibt das neue Secret über einen Passwortmanager an Ihre IT weiter.

1. Ab dem Erneuern signiert procuris 24 Stunden lang jede Nachricht an diese Zieladresse mit dem alten und dem neuen Secret. Beide Signaturen stehen im Header webhook-signature.
2. In dieser Zeit tragen Sie das neue Secret in Ihr System ein. Die Bibliotheken prüfen jede Signatur im Header. Ihr System läuft also ohne Unterbrechung weiter.
3. Nach 24 Stunden gilt nur noch das neue Secret.

Secret sofort ersetzen

Secret sofort ersetzen ist für ein öffentlich gewordenes Secret gedacht. Das alte Secret gilt ab dann nicht mehr, ohne 24 Stunden Übergang. Ihr System prüft jedoch weiter mit dem alten, bis Ihre IT das neue eingetragen hat. Tragen Sie es darum umgehend ein.

1. Die Inhaberin wählt bei der Zieladresse Secret sofort ersetzen und gibt das neue Secret über einen Passwortmanager an Ihre IT weiter.
2. Bis zum Eintragen scheitern die Nachrichten an der Prüfung. Ihr Empfänger beantwortet sie mit 401, und procuris stellt sie nach dem Wiederholplan erneut zu.
3. Ihre IT trägt das neue Secret ein und entfernt das alte.
4. Die Inhaberin prüft den Empfang mit Testnachricht senden.

Die Wiederholung setzt eine Ablehnung durch Ihren Empfänger voraus. Gemeint ist eine Antwort außer 2xx auf eine Nachricht mit ungültiger Signatur. Antwortet er trotzdem mit 2xx, wie manche Workflow-Builder, gilt die Nachricht als zugestellt. procuris wiederholt sie dann nicht. Solche Nachrichten holt die Inhaberin mit der Nachlieferung der letzten 7 Tage zurück. Dasselbe gilt, wenn das Eintragen länger dauert als der Wiederholplan und procuris die Nachrichten verworfen hat.

Ist niemand mit der Rolle Inhaber erreichbar, schreiben Sie an support@procuris.eu.

Absender erkennen

Die Signatur belegt die Echtheit, die Absenderadresse nicht. procuris veröffentlicht keine festen Absenderadressen für Firewall-Regeln. Prüfen Sie die Echtheit darum über die Signatur.

Verwandte Seiten

• Webhooks: erste Nachricht empfangen
• Ereignisse

Angebot anfordern

Schildern Sie uns, was Sie nutzen oder anbinden möchten. Ihr Angebot richtet sich nach diesem Umfang.

Angebot anfordern