Integrationen und Schnittstellen

API-Schlüssel

Ein API-Schlüssel erlaubt einem anderen System, Tickets in DeskHub anzulegen oder zu lesen (Adminportal → API-Schlüssel, nur echte Administratoren).

API-Schlüssel mit Rechten und IP-Beschränkung.

Beim Erstellen wird der Schlüssel (Format dh_ plus 48 Hexzeichen) nur einmal angezeigt – sofort notieren. In der Datenbank liegt nur eine Prüfsumme.
Pro Schlüssel legt ihr die Rechte fest („Tickets anlegen“ und/oder „Tickets lesen“) und optional die erlaubten IP-Adressen.
Schlüssel lassen sich jederzeit deaktivieren. Es gilt eine Begrenzung auf 60 über die API angelegte Tickets pro Minute (gemeinsam für alle Schlüssel).

Webhooks

Webhooks melden Ereignisse sofort an eine Adresse eures Systems (Adminportal → Webhooks): Name, URL und gewünschte Ereignisse wählen; das Secret zur Signaturprüfung legt ihr selbst fest oder lasst es erzeugen (es wird nur verschlüsselt gespeichert).

Webhooks mit Zustellstatus.

Ereignis	Wann
`ticket.created`	Neues Ticket (Portal, E-Mail, Chat, Mitarbeiter oder API)
`ticket.replied`	Antwort oder interne Notiz (Feld `author`, bei Mitarbeitern auch `internal`)
`ticket.status_changed`	Status geändert (Feld `previousStatus`)
`ticket.assigned`	Zuweisung geändert

Anfrage: POST mit JSON und den Headern X-DeskHub-Event und X-DeskHub-Signature (sha256= plus HMAC-SHA256 des rohen Körpers mit dem Secret). Gesendet werden nur Ticketdaten, nicht der Nachrichtentext.
Zustellung: Eure Adresse muss binnen 5 Sekunden mit 2xx antworten. Es gibt keine automatische Wiederholung. Nach 10 Fehlern in Folge wird der Webhook automatisch deaktiviert; Status, Fehlertext und Zeitpunkt stehen in der Liste.
Erlaubt sind http:// und https://, aber keine internen Ziele (localhost, private Netze). Nutzt https://.

Die Ticket-API für Entwickler

Basis-Adresse: https://support.example.de/api/public/v1/tickets.php (Beispieladresse). Jeder Aufruf braucht einen Schlüssel im Header X-API-Key oder Authorization: Bearer. Anfragen und Antworten sind JSON.

Aufruf	Recht	Zweck
`POST /api/public/v1/tickets.php`	Tickets anlegen	Ticket anlegen mit `name`, `email`, `subject`, `message` und optional `helpTopicId`, `departmentId`, `priorityId`, `fields` (Formularfelder) und `attachments` (bis 5 Dateien, Base64). Antwort `201` mit `{"number":"T-1042","status":"open"}`
`GET …tickets.php?topics=1`	Tickets anlegen	Öffentliche Hilfethemen
`GET …tickets.php?form=1&helpTopicId=3`	Tickets anlegen	Das Formular eines Themas oder einer Abteilung (Felder, Texte, Anhangsgrenzen)
`GET …tickets.php?number=T-1042&email=…`	Tickets lesen	Status und öffentliche Nachrichten (nie interne Notizen); falsche E-Mail ergibt 404

Fehler haben immer die Form {"error":{"code":"INVALID_EMAIL","message":"…"}}. Wichtige Codes: UNAUTHENTICATED (401), IP_NOT_ALLOWED (401), FORBIDDEN (403), BANNED/REJECTED (403), NOT_FOUND (404), TOO_LARGE (413), INVALID_* (422), RATE_LIMITED (429), NO_DEPARTMENT (503). Das Anlegen hat keine Wiederholungssicherung: Zweimal gesendet ergibt zwei Tickets.

WordPress-Plugin „DeskHub Tickets“

Besucher einer WordPress-Seite legen damit Tickets in DeskHub an ([deskhub_ticket]) und fragen den Stand ab ([deskhub_status]). Das Plugin nutzt die öffentliche Ticket-API und braucht nur einen API-Schlüssel (Recht „Tickets anlegen“, für die Statusabfrage zusätzlich „Tickets lesen“).

Formular mit den eigenen Feldern und Texten des Hilfethemas aus DeskHub (auch dem Formular der Abteilung), Einwilligungs-Kästchen, Anhänge (bis 5 Dateien, zusammen 10 MB).
Statusabfrage mit Verlauf.
Spamschutz: Falle-Feld, Mindestzeit, Mengenbegrenzung, optional Cloudflare Turnstile. Verbindungstest, Deutsch und Englisch.
Design: Farben übernimmt das Formular vom Theme; die Akzentfarbe lässt sich fest vorgeben.
Sicherheit: Der Schlüssel liegt nur auf dem WordPress-Server (oder in der wp-config.php), nie im Browser.

Das Plugin wurde mit einem Nachbau der WordPress-Funktionen und gegen einen echten DeskHub-Server getestet, noch nicht in einer echten WordPress-Installation.

Minecraft-Plugin

Eine Jar für Spigot, Paper und BungeeCord, die in DeskHub automatisch ein Ticket anlegt, wenn ein Minecraft-Server offline geht – und es nach der Rückkehr als gelöst markiert.

Wo es liegt	Erkennung	Ticket
BungeeCord-Proxy (empfohlen)	Prüft die Server von außen per Ping alle 30 Sekunden	nach 3 Fehlschlägen in Folge und wenn der Server länger als die Schonfrist (5 Minuten) fehlt
Spigot/Paper	Schreibt Lebenszeichen und markiert normales Beenden	beim nächsten Start nach einem Absturz oder harten Ende

Installation: API-Schlüssel mit Recht „Tickets anlegen“ (mit IP-Beschränkung auf den Minecraft-Server) erzeugen; Jar in den Ordner plugins; config.yml ausfüllen (url, api-key, requester-email, optional Abteilung und Priorität); /deskhubmc reload; mit /deskhubmc test ein Testticket anlegen.
Befehle: /deskhubmc test, /deskhubmc status, /deskhubmc reload (Alias /dhmc, Recht deskhubmc.admin).
Geplante Neustarts lassen sich dem Proxy signiert melden (längere Schonfrist, Standard 15 Minuten). Gegen Ticket-Fluten: pro Ausfall höchstens ein Ticket, pro Server frühestens nach 30 Minuten wieder eines.
Betreff und Text der Tickets sind anpassbar (Platzhalter {server}, {time}, {downtime} u. a.).

Auf der Seite „Apps“ steht das Minecraft-Plugin bereit, wenn es unter Einstellungen → Allgemein eingeblendet ist.