Pings (Nachrichten von externen Systemen)

Pings sind Kurznachrichten, die andere Systeme automatisch in die App schicken, ohne dass dort jemand etwas eintippt. Typische Absender sind ein Server-Monitoring, das Kassensystem, die Zeiterfassung oder eine Warenwirtschaft.

Was ist der Unterschied zu Nachrichten und Meldungen?

Nachrichten schreibt ein Mensch an ausgewählte Gruppen oder Personen.

Meldungen gehen von euch Mitarbeitern aus und basieren auf einem Formular.

Pings kommen von einer Maschine. Ein externes System schickt sie über eine Schnittstelle, die Empfänger stehen vorher fest.

Pings lesen

Ihr findet Pings im Tab Nachrichten in der Segment-Leiste oben unter Pings. Im Browser liegen sie in der Seitenleiste unter Pings.

Hinweis

Der Bereich Pings erscheint nur, wenn ihr bei mindestens einer Ping-Quelle als Empfänger eingetragen seid. Seht ihr ihn nicht, wendet euch an jemanden mit der Berechtigung „Pings verwalten“.

Übersicht

Jeder Eintrag zeigt euch:

• Name der Ping-Quelle: welches System die Nachricht geschickt hat, mit dessen Symbol und Farbe
• Nachricht: die ersten beiden Zeilen
• Zeitpunkt und ein Hinweis, wie viele Detailzeilen der Ping mitbringt
• Level: wie dringend die Nachricht ist

Level	Bedeutung
Info	Reine Information, kein Handlungsbedarf
Erfolg	Etwas hat geklappt, z. B. ein erfolgreicher Tagesabschluss
Warnung	Etwas läuft aus dem Ruder, aber noch nichts ist kaputt
Fehler	Etwas ist schiefgegangen und braucht Aufmerksamkeit

Neue Pings markiert ein roter Punkt an der Segment-Leiste und am Tab. Zieht die Liste nach unten, um zu aktualisieren.

Detailansicht

Tippt einen Ping an. Ihr seht die vollständige Nachricht und, falls das sendende System welche mitgeschickt hat, eine Tabelle mit Zusatzdaten. Was dort steht, bestimmt das sendende System frei, zum Beispiel:

Server	db01.intern
Job	nightly-db
Dauer	12 min 04 s
Exit-Code	3

Hat der Ping einen Link mitbekommen, findet ihr darunter die Schaltfläche Link öffnen. Damit springt ihr direkt ins auslösende System, z. B. zum betroffenen Monitoring-Job.

Wer die Berechtigung Pings verwalten hat, kann einen Ping über das Papierkorb-Symbol löschen.

Push-Benachrichtigungen

Kommt ein Ping herein, bekommen alle Empfänger der Quelle eine Push-Benachrichtigung, sofern für diese Quelle Push-Nachricht aktiviert ist. Als Titel erscheint der Name der Ping-Quelle. Ein Tipp auf die Benachrichtigung öffnet den Ping direkt.

Anders als bei News, Events und Nachrichten lässt sich das nicht im eigenen Profil abschalten. Die Entscheidung fällt zentral pro Ping-Quelle. Mehr zu Push allgemein: Push-Benachrichtigungen.

---

Ping-Quellen verwalten

Wer kann Ping-Quellen einrichten?

Dafür braucht ihr die Berechtigung Pings verwalten. Sie wird wie alle anderen Rechte über Gruppen vergeben, siehe Administration → Berechtigungen.

Jedes externe System, das Pings schicken darf, wird einmal als Ping-Quelle registriert und bekommt dabei einen eigenen API-Key. Nur mit diesem Key nimmt die Schnittstelle Nachrichten an.

Ihr findet den Bereich im Tab Verwaltung im Abschnitt „Verbindungen“ → Ping-Quellen, im Browser in der Seitenleiste unter Ping-Quellen.

Ping-Quelle anlegen

1. Tippt oben rechts auf das +.
2. Vergebt einen Namen. Er erscheint in der App als Überschrift jedes Pings. Wählt etwas, das die Empfänger sofort einordnen können, z. B. „Server-Monitor“ oder „Kassensystem Nord“.
3. Wählt ein Symbol und optional eine Farbe. Damit lassen sich mehrere Quellen in der Liste auf einen Blick unterscheiden.
4. Legt die Empfänger fest: ganze Gruppen und/oder einzelne Mitarbeiter.
5. Stellt das Verhalten ein (siehe unten).
6. Tippt auf Anlegen.

Danach erscheint der Abschnitt Schnittstelle mit Endpunkt-URL und API-Key.

Wichtig

Die Empfänger steuern beides: wer die Push-Nachricht bekommt und wer die Pings überhaupt sehen darf. Wer nicht eingetragen ist, sieht die Pings dieser Quelle nicht, auch nicht mit der Berechtigung „Pings verwalten“. Tragt euch also selbst ein, wenn ihr mitlesen möchtet.

Einstellungen

Einstellung	Bedeutung
Aktiv	Nur aktive Quellen nehmen Pings an. Deaktiviert ihr eine Quelle, bleiben alte Pings lesbar.
Push-Nachricht	Ob bei jedem Ping eine Push-Benachrichtigung rausgeht. Für gesprächige Systeme besser aus.
Aufbewahrung (Tage)	Ältere Pings werden täglich automatisch gelöscht. Standard 90 Tage, 0 = unbegrenzt.

API-Key weitergeben und wechseln

Den API-Key hinterlegt ihr im sendenden System. Über das Kopier-Symbol landet er in der Zwischenablage.

Ist ein Key in falsche Hände geraten, tippt auf API-Key neu erzeugen.

Der alte Key wird sofort ungültig

Alle Systeme, die den bisherigen Key verwenden, bekommen ab diesem Moment eine Fehlermeldung und müssen umgestellt werden. Plant den Wechsel also ein, statt ihn nebenbei zu machen.

Ping-Quelle löschen

Beim Löschen einer Quelle werden alle bereits empfangenen Pings dieser Quelle mitgelöscht. Wollt ihr nur verhindern, dass neue hereinkommen, schaltet die Quelle stattdessen auf inaktiv.

---

Die Schnittstelle

Dieser Abschnitt richtet sich an alle, die das sendende System einrichten.

Endpunkt

POST https://api.staffdeck.app/v1/ping

Eigene Adresse

Läuft StaffDeck bei euch unter einer eigenen Domain oder im eigenen Rechenzentrum, ersetzt ihr die Basis-Adresse entsprechend. Der Pfad /v1/ping bleibt gleich. Welche Adresse bei euch gilt, weiß euer Administrator.

Der API-Key gehört in den Header X-Api-Key. Alternativ wird Authorization: Bearer <key> akzeptiert, falls euer System nur damit umgehen kann.

Felder

Feld	Pflicht	Beschreibung
message	ja	Der Nachrichtentext, maximal 2000 Zeichen
level	nein	info (Standard), success, warning oder error
data	nein	Zusatzdaten, die in der App als Tabelle erscheinen
link	nein	Link zurück ins sendende System, muss mit http:// oder https:// beginnen

Einen Titel gibt es bewusst nicht. Als Überschrift dient immer der Name der Ping-Quelle.

Beispiel

curl -X POST https://api.staffdeck.app/v1/ping \
  -H "X-Api-Key: png_7f3c9e1a…" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Sicherung von db01 ist abgebrochen.",
    "level": "error",
    "link": "https://monitor.intern/jobs/nightly-db/914",
    "data": {
      "Server": "db01.intern",
      "Job": "nightly-db",
      "Dauer": "12 min 04 s",
      "Exit-Code": 3
    }
  }'

Antwort bei Erfolg:

{
  "success": true,
  "errorCode": 201,
  "id": 42,
  "uuid": "dffd4649-938b-47e0-8203-8c287ea53e59",
  "recipients": 5
}

recipients sagt euch, an wie viele Personen der Ping ausgeliefert wurde. Steht dort 0, hat die Quelle keine Empfänger. Der Ping ist zwar gespeichert, aber niemand sieht ihn.

Zusatzdaten mitgeben

data akzeptiert drei Schreibweisen. Alle drei ergeben dieselbe Tabelle. Nehmt die, die euer System ohnehin erzeugt:

{ "Server": "db01", "Dauer": "12 min" }

[
  { "label": "Server", "value": "db01" },
  { "label": "Dauer", "value": "12 min" }
]

[["Server", "db01"], ["Dauer", "12 min"]]

Zahlen und Wahrheitswerte werden automatisch zu Text (true wird zu „Ja“), verschachtelte Objekte als JSON dargestellt. Die Reihenfolge bleibt so, wie ihr sie schickt.

Grenzen

Maximal 50 Zeilen pro Ping, Bezeichnungen bis 100 und Werte bis 500 Zeichen. Längeres wird abgeschnitten, der Ping kommt trotzdem an. Der gesamte Request darf 64 KB nicht überschreiten.

Weitere Beispiele

Nächtliches Backup-Skript (Bash), das Erfolg oder Fehler meldet:

#!/usr/bin/env bash
PING_KEY="png_7f3c9e1a…"
START=$(date +%s)

if pg_dump -Fc app > /backup/app.dump; then
  LEVEL="success"; TEXT="Sicherung erfolgreich abgeschlossen."
else
  LEVEL="error";   TEXT="Sicherung ist fehlgeschlagen."
fi

curl -sS -X POST https://api.staffdeck.app/v1/ping \
  -H "X-Api-Key: $PING_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg l "$LEVEL" --arg t "$TEXT" \
        --arg d "$(( $(date +%s) - START )) s" --arg h "$(hostname)" \
        '{message: $t, level: $l, data: {Server: $h, Dauer: $d}}')"

Kassensystem (PHP) für den Tagesabschluss:

$payload = [
    "message" => "Tagesabschluss erfolgreich übermittelt.",
    "level"   => "success",
    "data"    => [
        "Umsatz brutto"   => number_format($umsatz, 2, ",", ".") . " €",
        "Bons"            => $bons,
        "Stornos"         => $stornos,
        "Kassendifferenz" => number_format($differenz, 2, ",", ".") . " €",
    ],
];

$ch = curl_init("https://api.staffdeck.app/v1/ping");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["X-Api-Key: png_7f3c9e1a…", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
]);
curl_exec($ch);

Warenwirtschaft (PHP) als wiederverwendbare Funktion, die die Antwort auswertet:

function sendePing(array $payload): bool
{
    $ch = curl_init("https://api.staffdeck.app/v1/ping");
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_HTTPHEADER     => [
            "X-Api-Key: " . getenv("PING_KEY"),
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS     => json_encode($payload, JSON_UNESCAPED_UNICODE),
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
    ]);

    $body   = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status !== 201) {
        error_log("Ping abgelehnt ($status): $body");
        return false;
    }

    return true;
}

sendePing([
    "message" => "Bestellung konnte nicht an die Warenwirtschaft übergeben werden.",
    "level"   => "error",
    "link"    => "https://shop.intern/bestellungen/20418",
    "data"    => [
        "Bestellnummer" => "20418",
        "Kunde"         => "Muster GmbH",
        "Betrag"        => "1.248,00 €",
        "Fehler"        => "Zeitüberschreitung nach 30 s",
    ],
]);

Deployment-Meldung (Node.js) ohne zusätzliche Pakete, ab Node 18:

async function sendePing(payload) {
  const response = await fetch("https://api.staffdeck.app/v1/ping", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.PING_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  const result = await response.json();

  if (!response.ok) {
    throw new Error(`Ping abgelehnt (${response.status}): ${result.error}`);
  }

  console.log(`Ping an ${result.recipients} Empfänger zugestellt.`);
}

sendePing({
  message: "Deployment v1.24.0 auf Produktion abgeschlossen.",
  level: "success",
  link: "https://ci.intern/builds/8412",
  data: {
    Umgebung: "production",
    Version: "v1.24.0",
    Commit: process.env.GIT_COMMIT,
    Dauer: "2 min 47 s",
  },
}).catch(error => console.error(error.message));

Überwachungs-Skript (Python) mit Warnung bei knappem Speicherplatz:

import shutil, requests

total, used, free = shutil.disk_usage("/var")
belegt = used / total

if belegt > 0.9:
    requests.post(
        "https://api.staffdeck.app/v1/ping",
        headers={"X-Api-Key": "png_7f3c9e1a…"},
        json={
            "message": "Der Speicherplatz auf /var wird knapp.",
            "level": "warning",
            "data": {
                "Mountpoint": "/var",
                "Belegt": f"{belegt:.0%}",
                "Frei": f"{free / 1024**3:.1f} GB",
            },
        },
        timeout=10,
    )

Ohne Zusatzdaten, die kürzestmögliche Variante:

curl -X POST https://api.staffdeck.app/v1/ping \
  -H "X-Api-Key: png_7f3c9e1a…" -H "Content-Type: application/json" \
  -d '{"message": "Wartungsfenster beendet, keine Auffälligkeiten."}'

Antwortcodes

Code	Bedeutung
201	Ping angenommen
400	Ungültige Anfrage: message fehlt, JSON ist kaputt oder link ist ungültig
401	API-Key fehlt, ist falsch, oder die Ping-Quelle ist deaktiviert
413	Der Request ist größer als 64 KB
429	Zu viele Pings: maximal 60 pro Minute und Quelle

Bei 429 liefert die Antwort einen Retry-After-Header mit. Löst euer System sehr häufig aus, fasst mehrere Ereignisse lieber in einem Ping zusammen, statt jedes einzeln zu schicken.

Erst testen, dann automatisieren

Schickt nach dem Anlegen einer Quelle einmal den curl-Befehl aus dem Abschnitt Schnittstelle von Hand. Erscheint der Ping in der App, stimmen Key, Empfänger und Erreichbarkeit. Erst dann baut ihr ihn ins System ein.

---

Häufige Fragen

Ich sehe den Bereich „Pings“ nicht

Ihr seid bei keiner Ping-Quelle als Empfänger eingetragen. Wer die Berechtigung „Pings verwalten“ hat, kann euch oder eure ganze Gruppe bei der passenden Quelle hinzufügen.

Der Ping kommt an, aber niemand bekommt eine Benachrichtigung

Prüft in der Ping-Quelle, ob Push-Nachricht aktiviert ist. Prüft außerdem, ob die Antwort der Schnittstelle bei recipients eine Zahl größer 0 zurückgibt.

Ich bekomme 401, obwohl der Key stimmt

Prüft, ob die Ping-Quelle auf Aktiv steht. Eine deaktivierte Quelle weist Pings mit demselben Fehler ab wie ein falscher Key. Prüft außerdem, ob beim Kopieren ein Leerzeichen mitgekommen ist.

Alte Pings sind verschwunden

Jede Ping-Quelle hat eine Aufbewahrung in Tagen (Standard 90). Ältere Pings werden täglich automatisch gelöscht. Wollt ihr sie dauerhaft behalten, setzt den Wert auf 0.