Webhooks einrichten

Jupiter ERP kann fachliche Ereignisse an eine HTTPS-Adresse senden, die Sie selbst hinterlegen. Damit stoßen Sie Abläufe in einem anderen System an, ohne die Daten dort regelmäßig abzufragen. Die Einrichtung liegt unter System → Webhooks.

Webhooks sind in der Testphase und im Enterprise-Paket enthalten, mit bis zu fünf Endpunkten. Andere Tarife enthalten sie nicht. Den Umfang sehen Sie unter System → Abonnement.

Ein Ereignis geht nur an Endpunkte, die aktiv sind und dieses Ereignis abonniert haben. Die Option Alle Ereignisse nimmt jeden Typ an. Dieselbe Ereigniskennung kann an mehrere Endpunkte gehen. Jeder Endpunkt hat seine eigene Zustellung.

Endpunkt anlegen

1. Öffnen Sie System → Webhooks. Der Tab Endpunkte ist vorausgewählt.
2. Klicken Sie auf Webhook anlegen. Vergeben Sie einen Namen und eine öffentliche HTTPS-Adresse. Private Adressen und Weiterleitungen nimmt Jupiter ERP nicht an.
3. Wählen Sie die Ereignisse, die dieser Endpunkt erhalten soll, oder alle Ereignisse.
4. Kopieren Sie das Signaturgeheimnis sofort. Es erscheint nur beim Anlegen und beim Erneuern. Eigene Header, zum Beispiel ein API-Schlüssel, hinterlegen Sie am Endpunkt über Header hinzufügen. Content-Type, User-Agent und Jupiter-ERP-Signature setzt Jupiter ERP selbst.

Jede Zustellung ist ein POST mit JSON. Der Header Jupiter-ERP-Signature hat die Form t=1710000000,v1=…. t ist der Unix-Zeitstempel. v1 ist eine HMAC-SHA256 über den Text Zeitstempel.Nachricht, berechnet mit dem Geheimnis, als Hex. Die Nachricht ist der Rohtext des Bodys, nicht ein neu formatiertes JSON. Der Header User-Agent lautet Jupiter-ERP-Webhook/1.0. Behandeln Sie das Geheimnis wie ein Passwort. Vergleichen Sie den Zeitstempel mit der aktuellen Uhrzeit und lehnen Sie alte Nachrichten ab.

Antworten Sie auf derselben Adresse innerhalb von 10 Sekunden mit einem Status 2xx. Erledigen Sie die eigentliche Arbeit danach. Jupiter ERP folgt keinen Weiterleitungen.

Über das Menü des Endpunkts senden Sie einen Test, schalten den Endpunkt aus oder wieder ein, erneuern das Geheimnis oder löschen den Endpunkt. Lesen, Anlegen, Ändern und Löschen sind getrennte Berechtigungen. Test und Erneuern gehören zum Ändern.

Test mit webhook.ping

webhook.ping ist kein fachlicher Vorgang. Es startet nur, wenn Sie an einem aktiven Endpunkt Test senden wählen.

Jupiter ERP legt dann ein echtes Ereignis vom Typ webhook.ping an und stellt es nur an diesen Endpunkt zu. Die Auswahl der Ereignisse spielt dafür keine Rolle. webhook.ping in der Liste zu markieren löst keine automatischen Tests aus.

Ein ausgeschalteter Endpunkt nimmt keinen Test an. Schalten Sie ihn zuerst ein.

Die Hülle ist dieselbe wie bei den anderen Ereignissen. Signatur, Wiederholung und der Eintrag unter Zustellungen gelten auch für den Test.

{
  "id": "evt_01J...",
  "type": "webhook.ping",
  "api_version": "1.0.0",
  "created_at": "2026-10-10T19:00:00+00:00",
  "account_uuid": "…",
  "data": {
    "object": "ping",
    "item": { "ok": true }
  }
}

Die id beginnt mit evt_.

Wann ein Ereignis gesendet wird

Jupiter ERP speichert ein fachliches Ereignis nur, wenn mindestens ein aktiver Endpunkt es abonniert hat. Sonst entsteht kein Eintrag.

Inhalt der Nachricht

Neben den Feldern aus dem Test enthalten fachliche Nachrichten in data.item eine Kurzfassung. Den vollständigen Datensatz lesen Sie über die Account API (siehe API- und MCP-Zugang verwalten). Die technische Referenz steht unter https://www.jupiter-erp.com/referenz/webhooks.

Beträge stehen in Cent. 450 sind 4,50 in der gewählten Währung.

Rechnungen, Gutschriften und Angebote enthalten Kennung, Status, Nummer, formatierten Nummernkreis, Datum, Netto, Brutto, Währung und, soweit vorhanden, Kontakt, Projekt und Kostenstelle mit Name. Belege haben keine Rechnungsnummer. Sie enthalten Belegart, Referenz, Ausstellerreferenz, Datum, Beträge und dieselben Zuordnungen. Kontakte enthalten Art, Name, Firmenname und Kontaktnummer. Signaturen enthalten Status sowie Art und Kennung des Dokuments.

Zustellungen

Der Tab Ereignisse zeigt die gespeicherten Events mit Filter nach Typ und Zeitraum. Der Tab Zustellungen zeigt je Nachricht Status, Endpunkt, Zeitpunkt und die einzelnen Versuche.

Antwortet die Gegenstelle mit 2xx, ist die Zustellung erledigt. Status 410 schaltet den Endpunkt sofort ab. 429, 5xx, Zeitüberschreitung und Netzwerkfehler werden wiederholt: nach etwa 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 8 Stunden und 12 Stunden. Die Abstände schwanken etwas. Nach dem siebten Versuch gilt die Zustellung als fehlgeschlagen. Andere 4xx-Antworten und Weiterleitungen werden nicht wiederholt.

Zehn fehlgeschlagene Zustellungen in Folge schalten den Endpunkt ab. Eine erfolgreiche Zustellung setzt den Zähler zurück. Sie aktivieren den Endpunkt wieder, sobald die Adresse erreichbar ist. Eine fehlgeschlagene oder abgebrochene Zustellung können Sie erneut senden.

Wechselt der Tarif von der Testphase oder von Enterprise auf einen Tarif ohne Webhooks, werden alle Endpunkte ausgeschaltet. Offene Zustellungen werden abgebrochen. Adresse, Geheimnis und Verlauf bleiben. Kommt das Feature zurück, bleiben die Endpunkte aus, bis jemand sie wieder einschaltet.

Häufige Fragen

Kann ich Webhooks mit einem API-Token verwalten?

Ja, über die Account API, wenn das Token die passende Webhook-Berechtigung hat. Die Einrichtung im Panel bleibt unter System → Webhooks. Das Signaturgeheimnis erscheint auch über die API nur beim Anlegen und beim Erneuern. Token legen Sie unter API- und MCP-Zugang verwalten an.

Warum kommt ein Ereignis mehrfach an?

Eine Zustellung wird wiederholt, wenn die Gegenstelle nicht rechtzeitig mit Erfolg antwortet. Dieselbe Ereigniskennung bedeutet denselben Vorgang. Verarbeiten Sie sie nur einmal.

Verwandte Artikel

• API- und MCP-Zugang verwalten
• Abonnement und Tarif verwalten