Webhooks
procuris meldet neue Ausschreibungen und Treffer von sich aus an Ihr System. Wann Webhooks statt der API passen und wie Ihre IT die erste Nachricht empfängt.
Diese Leistung erhalten Sie über ein individuelles Angebot.
Webhooks melden Ereignisse, ohne dass Ihr System nachfragt. Ein Webhook ist eine Nachricht, die procuris von sich aus an eine Web-Adresse Ihres Systems schickt, sobald ein gewähltes Ereignis eintritt. Für die gewählten Ereignisse entfällt damit der regelmäßige Abruf. Ihr CRM legt so zum Beispiel einen neuen Treffer als Verkaufschance an, ohne dass jemand ihn aus procuris abschreibt. Den Bestand von vor der Einrichtung liefern Webhooks jedoch nicht, den holt die API. Beide tragen denselben Datensatz.
Individuelles Angebot
Webhooks erhalten Sie über ein individuelles Angebot. Sie fragen über den Kontakt-Block unten auf dieser Seite an oder in procuris unter Einstellungen › Organisation im Abschnitt Auf Anfrage mit Webhooks. Den Weg von der Anfrage bis zum eingerichteten Zugang und wer die Anbindung baut, beschreibt Integrationen. Nach der Einrichtung verwaltet die Person mit der Rolle Inhaber die Webhooks selbst.
Welche Ereignisse es gibt
Sechs Ereignisse decken Ausschreibungen, Treffer und den Test ab:
- Neue Ausschreibung, die zu Ihren Filtern passt (
tender.published) - Geänderte Ausschreibung, zum Beispiel neuer Auftragswert oder neue Lose (
tender.updated) - Verschobene Frist (
tender.deadline_changed) - Ausschreibung beendet: abgelaufen, aufgehoben, vergeben oder mit einem anderen Datensatz zusammengeführt (
tender.archived) - Neuer Treffer eines Suchauftrags mit seiner Passung von 0 bis 100 (
search.hit). Ein Suchauftrag ist eine gespeicherte Suche, die jeden Morgen weiterläuft. - Testnachricht, die Sie in procuris auslösen (
webhook.test)
Ausschreibungs-Ereignisse kommen bis zu eine Stunde nach der Übernahme durch procuris. Bezugspunkt ist der Zeitpunkt, zu dem procuris die Änderung übernommen hat (lastModified), nicht die Änderung bei der Vergabestelle. Treffer kommen einmal am Morgen mit dem Lauf des Suchauftrags. Einzelheiten und Beispiele stehen unter Ereignisse.
Webhook oder API?
Webhooks passen, wenn Ihr System erreichbar ist und reagieren soll. Die API passt, wenn Ihr System nach eigenem Zeitplan abruft oder den Bestand braucht.
| Lage | Weg |
|---|---|
| Ihr System soll ohne eigenen Zeitplan reagieren, zum Beispiel neue Treffer an ein Team geben | Webhook |
| Ihr System ist von außen nicht erreichbar, zum Beispiel hinter einer Firewall ohne eingehende Verbindungen | API, Ihr System ruft stündlich ab |
| Erstbefüllung, also das einmalige Laden des vorhandenen Bestands | API, weil Webhooks nur melden, was ab der Einrichtung des Zugangs passiert |
| Nächtlicher Ladelauf ins BI-Werkzeug | API |
| CRM mit allen Ausschreibungen zu Ihren Filtern führen (Variante A) | beides: API für die Erstbefüllung und den nächtlichen Abgleich, Webhooks für Änderungen |
| CRM nur mit den Treffern Ihrer Suchaufträge führen (Variante B) | nur Webhooks mit search.hit, tender.updated und tender.archived, ohne Erstbefüllung |
Variante B braucht keine API, beginnt aber leer. Die ersten Treffer kommen am Morgen nach der Einrichtung. Beide Varianten beschreibt CRM und ERP Schritt für Schritt.
Was Ihre IT bereitstellt
Ihre IT stellt drei Dinge bereit:
- eine Adresse mit HTTPS, die aus dem Internet erreichbar ist und
POST-Anfragen annimmt - die Prüfung der Signatur, mit fertigen Bibliotheken unter anderem für Python, JavaScript, Java, Go und C#, siehe Zustellung und Sicherheit
- eine Antwort mit Status 2xx innerhalb von 15 Sekunden
Für kurze Abläufe wie eine Teams-Nachricht genügt ein Workflow-Builder. Für ein CRM bauen Sie statt eines Builders einen eigenen Empfänger, weil der Abgleich doppelte Nachrichten erkennen und ältere Stände übergehen muss, siehe CRM und ERP.
Ihre erste Nachricht empfangen
In procuris eintragen kann nur die Rolle Inhaber. Sie richtet Webhooks unter Einstellungen › Organisation › Webhooks ein. Der Bereich 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. Ihre IT baut den Empfänger und ermittelt die Werte, während die Inhaberin sie in procuris einträgt. Hat die IT-Verantwortliche selbst die Rolle Inhaber, erledigt sie beides.
Adresse mit HTTPS bereitstellen. procuris schickt nur an HTTPS-Adressen, auch die Testnachricht. Für einen ersten Versuch an einem Rechner ohne eigene Web-Adresse reicht ein Tunnel-Dienst, der eine HTTPS-Adresse auf Ihren Rechner weiterleitet. Für den Betrieb nehmen Sie statt des Tunnels eine feste Adresse Ihres Systems oder eines Workflow-Builders, weil die Tunnel-Adresse nur erreichbar ist, solange Ihr Rechner läuft.
Zieladresse anlegen. Die Inhaberin legt unter Webhooks eine Zieladresse an und trägt Ihre Adresse ein. Sie wählt dort die Ereignisse, die Filter und die Suchaufträge, siehe Ereignisse. Adresse und Auswahl kann sie später ändern oder die Zieladresse löschen.
Secret weitergeben. procuris erzeugt für jede neue Zieladresse ein eigenes Signatur-Secret. Die Inhaberin gibt es an Ihre IT weiter, über einen Passwortmanager statt per E-Mail oder Chat, weil Nachrichten dort lange lesbar bleiben.
Empfänger einrichten. Ihr Empfänger nimmt POST-Anfragen an und prüft die Signatur mit
einer der fertigen Bibliotheken aus Zustellung und
Sicherheit. Er legt die Nachricht ab und antwortet
innerhalb von 15 Sekunden mit 204. Eine Nachricht mit falscher Signatur beantwortet er mit 401
und verwirft sie.
Testnachricht senden. Unter Webhooks schickt Testnachricht senden eine Nachricht vom
Typ webhook.test an die Zieladresse. Sie trägt den Musterdatensatz unter data.tender und
data.test gleich true. procuris zeigt daneben die Antwort Ihres Empfängers an. Steht dort
ein Status 2xx, ist der Empfang bereit.
Echte Nachrichten verarbeiten. Ab jetzt kommen die gewählten Ereignisse. Den Aufbau der Nachrichten beschreibt Ereignisse.
Im Betrieb selbst verwalten
Die Inhaberin ändert Webhooks ohne Umweg über den Support. Unter Webhooks stehen ihr diese Aufgaben offen:
- Zieladressen anlegen, ändern und löschen, je Zieladresse Ereignisse, Filter und Suchaufträge wählen
- Secret erneuern für den geplanten Wechsel, mit 24 Stunden Übergang, in denen altes und neues Secret gelten
- Secret sofort ersetzen, wenn ein Secret öffentlich geworden ist. Das alte gilt ab dann nicht mehr. Nachrichten scheitern, bis Ihre IT das neue eingetragen hat, und kommen danach nach dem Wiederholplan erneut.
- Testnachricht senden, zum Beispiel nach einem Umbau Ihres Empfängers
- Zustellung wieder aufnehmen, nachdem procuris sie eingestellt hat: nach 5 Tagen ohne erfolgreiche Zustellung oder nach der Antwort 410 Ihres Systems
- verpasste Nachrichten der letzten 7 Tage erneut senden. Ältere Lücken bei Ausschreibungs-Ereignissen holt nur ein System mit API-Zugang nach. Ältere Treffer lassen sich nicht nachholen.
Die Abläufe im Einzelnen stehen unter Zustellung und Sicherheit. Ist niemand mit der Rolle Inhaber erreichbar, hilft support@procuris.eu als Notfallweg.
Auf einen Blick
| Merkmal | Wert |
|---|---|
| Standard | Standard Webhooks, eine offene Spezifikation mit Prüf-Bibliotheken für viele Sprachen |
| Transport | POST über HTTPS, Inhalt als JSON |
| Echtheit | HMAC-SHA256 in den Headern webhook-id, webhook-timestamp, webhook-signature |
| Erfolg | Status 2xx innerhalb von 15 Sekunden |
| Wiederholung | bis zu neun weitere Versuche über gut drei Tage |
| Verwaltung | durch die Rolle Inhaber unter Einstellungen › Organisation › Webhooks |
Angebot anfordern
Schildern Sie uns, was Sie nutzen oder anbinden möchten. Ihr Angebot richtet sich nach diesem Umfang.