Incoming Webhooks

Incoming Webhooks erlauben externen Tools, automatische Nachrichten in einen HansaChat Kanal zu schreiben. Nutzen Sie sie für Deployment-Updates, Monitoring-Warnungen, Ticket-Benachrichtigungen, Formular-Einsendungen und andere Ereignisse, die im Teamchat erscheinen sollen.

Nur Workspace-Administratoren können Incoming Webhooks erstellen und verwalten.

Webhooks über Settings öffnen

Webhook erstellen

Öffnen Sie Settings unten links in der Seitenleiste.
Wählen Sie Webhooks.
Wählen Sie Create webhook.
Geben Sie einen klaren Namen ein, zum Beispiel CI Deployments.
Wählen Sie den Kanal, in den Nachrichten geschrieben werden sollen.
Geben Sie optional eine Icon-URL ein.
Wählen Sie Create webhook.

Leere Webhooks-Seite

Formular zum Erstellen eines Webhooks

Webhook-URL kopieren

Nach dem Erstellen zeigt HansaChat die Webhook-URL einmalig an. Kopieren Sie sie und speichern Sie sie sicher in dem externen Tool, das Ereignisse senden soll.

Webhook-URL wird einmalig angezeigt

Wenn Sie diesen Bildschirm schließen, ohne die URL zu speichern, rotieren Sie die URL, um ein neues Secret zu erzeugen. Die vorherige URL funktioniert nach der Rotation sofort nicht mehr.

Webhooks verwalten

Auf der Webhooks-Seite können Admins:

den Namen, Kanal, die Icon-URL oder den aktiven Status bearbeiten.
einen Webhook deaktivieren, damit neue Nachrichten abgelehnt werden, ohne ihn zu löschen.
die URL rotieren, um das alte Secret ungültig zu machen und eine neue URL zu erzeugen.
einen Webhook löschen. Bereits gesendete Chatnachrichten werden dabei nicht entfernt.

Technische Referenz

Senden Sie einen POST Request an die Webhook-URL:

https://{workspace-domain}/api/webhooks/{publicID}/{secret}

Die URL enthält die Zugangsdaten für den Webhook. Es ist kein zusätzlicher Authentifizierungs-Header erforderlich. Behandeln Sie die vollständige URL vertraulich.

Minimaler Request

curl -X POST 'https://{workspace-domain}/api/webhooks/{publicID}/{secret}' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Deployment completed successfully"}'

Nachdem HansaChat mit ok antwortet, erscheint die Nachricht im ausgewählten Kanal.

Webhook-Testnachricht in einem Kanal

Slack-kompatibles Payload

Der Endpoint akzeptiert Slack-kompatible JSON-Payloads mit text, blocks und attachments.

{
  "text": "Deployment completed successfully",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Deployment completed"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Branch `main` is now live."
      }
    }
  ]
}

Mindestens eines der Felder text, blocks oder attachments muss lesbaren Text enthalten.

Unterstützte Felder

Feld	Erforderlich	Hinweise
`text`	Nein	Einfacher Nachrichtentext.
`blocks`	Nein	Slack Block Kit-ähnliche Blocks. Bis zu 50 Blocks. Unterstützte Blocktypen: `section`, `header`, `context`, `image`.
`attachments`	Nein	Slack-ähnliche Attachments. Bis zu 100 Attachments.

Die maximale Payload-Größe beträgt 1 MB.

Rate Limits

Incoming-Webhook-Ingestion ist pro Webhook-URL rate-limited.

Jeder Webhook akzeptiert bis zu 10 authentifizierte Requests pro Minute und bis zu 100 authentifizierte Requests pro Stunde. Wenn eines der Limits erreicht ist, antwortet HansaChat mit 429 resource_exhausted.

Bitte kontaktieren Sie uns, wenn Sie das Rate Limit erhöhen möchten.

Payload-Limits werden separat durchgesetzt: maximale Body-Größe 1 MB, blocks akzeptiert bis zu 50 Einträge, attachments akzeptiert bis zu 100 Einträge, und die Payload muss lesbaren Text enthalten.

Idempotenz

Setzen Sie den Header Idempotency-Key, wenn Ihr System dasselbe Ereignis erneut senden könnte:

curl -X POST 'https://{workspace-domain}/api/webhooks/{publicID}/{secret}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: deploy-1247' \
  -d '{"text":"Deployment #1247 completed"}'

Wenn HansaChat denselben Idempotency Key für denselben Webhook erneut erhält, antwortet es mit 200 ok, ohne eine doppelte Nachricht zu erstellen.

Antworten

Erfolgreiche Requests antworten mit:

ok

Häufige Fehler:

Status	Body	Bedeutung
400	`invalid_payload`	Der JSON Body konnte nicht gelesen werden.
400	`invalid_blocks`	Der Request enthält mehr als 50 Blocks.
400	`too_many_attachments`	Der Request enthält mehr als 100 Attachments.
400	`no_text`	Das Payload enthält keinen lesbaren Text.
429	`resource_exhausted`	Der Webhook hat 10 Requests pro Minute oder 100 Requests pro Stunde überschritten.
404	`no_active_hooks`	Workspace, Webhook, Secret oder aktiver Status ist ungültig.
410	`channel_is_archived`	Der Zielkanal ist archiviert.
503	`temporarily_unavailable`	HansaChat kann die Nachricht gerade nicht verarbeiten. Versuchen Sie es später mit demselben `Idempotency-Key` erneut.

Sicherheitstipps

Behandeln Sie Webhook-URLs wie Passwörter.
Speichern Sie URLs im Secret Manager des externen Tools.
Rotieren Sie die URL, wenn sie offengelegt wurde oder verloren ging.
Deaktivieren Sie nicht verwendete Webhooks.
Verwenden Sie pro externem System einen eigenen Webhook, damit Zugriff sauber entzogen werden kann.