Ausgehende Ereignis-Webhooks

Diese Seite erläutert ausgehende Ereignis-Webhooks: Almirant sendet Benachrichtigungen über Projektereignisse an deinen Server. Um einen Agenten aus einem externen System zu starten, verwende Agenten-Webhooks.

Almirant sendet ausgehende HTTP-Benachrichtigungen an deinen Server, wenn Ereignisse in deinen Projekten auftreten. Jedes Mal, wenn ein Work Item erstellt, zwischen Spalten verschoben oder ein Sprint geschlossen wird, sendet Almirant eine POST-Anfrage an die von dir konfigurierte URL.

Dies ist nützlich für:

• Die Synchronisierung von Almirant mit externen Tools (Slack, Discord, deinem eigenen Dashboard)
• Das Auslösen von CI/CD-Pipelines, wenn eine Aufgabe ihren Status ändert
• Die Versorgung von Analytics- oder Reporting-Systemen
• Die Automatisierung benutzerdefinierter Abläufe außerhalb von Almirant

Einen Webhook erstellen

1. Gehe in deinem Projekt zu Einstellungen > Webhooks
2. Klicke auf Webhook erstellen
3. Fülle die Felder aus:

Feld	Beschreibung	Beispiel
URL	HTTPS-Endpoint, der die Benachrichtigungen empfängt	https://mi-servidor.com/webhooks/almirant
Ereignisse	Ereignistypen, die den Webhook auslösen	work_item.created, sprint.closed
Secret	Geheimer Schlüssel zur Validierung der Authentizität der Anfragen	Wird automatisch generiert oder du kannst einen eigenen festlegen

4. Klicke auf Speichern

Wichtig

Die URL muss über das Internet erreichbar sein und HTTPS verwenden. Almirant sendet keine Webhooks an unverschlüsselte HTTP-URLs (außer an localhost während der Entwicklung).

Verfügbare Ereignisse

Wähle beim Erstellen des Webhooks ein oder mehrere Ereignisse aus:

Ereignis	Wird ausgelöst, wenn ...
work_item.created	Ein neues Work Item erstellt wird
work_item.updated	Felder eines Work Items geändert werden (Titel, Beschreibung, Priorität usw.)
work_item.moved	Ein Work Item zwischen Spalten des Boards verschoben wird
work_item.archived	Ein Work Item archiviert wird
lead.created	Ein neuer Lead im CRM erstellt wird
lead.updated	Daten eines Leads aktualisiert werden
lead.stage_changed	Ein Lead die Phase im Funnel wechselt
sprint.created	Ein neuer Sprint erstellt wird
sprint.closed	Ein Sprint geschlossen wird

Tipp

Wenn du nur auf Änderungen im Board reagieren musst, wähle ausschließlich die Ereignisse work_item.* aus. Je weniger Ereignisse du abonnierst, desto weniger Traffic erhält dein Server.

Die Webhook-Signatur überprüfen

Jede Anfrage enthält eine HMAC-SHA256-Signatur im Header X-Almirant-Signature, mit der du überprüfen kannst, dass die Anfrage tatsächlich von Almirant stammt und nicht manipuliert wurde.

So funktioniert die Überprüfung

1. Almirant erzeugt einen HMAC-SHA256-Hash des Anfrage-Bodys und verwendet dafür dein Secret als Schlüssel
2. Der Hash wird im Header X-Almirant-Signature eingefügt
3. Dein Server berechnet den Hash mit demselben Secret neu und vergleicht ihn

Beispiel in Node.js

import crypto from 'node:crypto';

function verifyWebhookSignature(body, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In deinem Endpoint:
app.post('/webhooks/almirant', (req, res) => {
  const signature = req.headers['x-almirant-signature'];
  const rawBody = req.rawBody; // Body als String, nicht geparst

  if (!verifyWebhookSignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Firma invalida' });
  }

  const event = JSON.parse(rawBody);
  console.log('Evento recibido:', event.type);

  // Das Ereignis verarbeiten ...

  res.status(200).json({ received: true });
});

Beispiel in Python

import hmac
import hashlib

def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Sicherheit

Überprüfe die Signatur immer, bevor du das Ereignis verarbeitest. Vertraue niemals Webhook-Daten, ohne ihre Authentizität zu validieren. Verwende timingSafeEqual (oder eine Entsprechung), um Timing-Angriffe zu verhindern.

Zustellungsprotokolle anzeigen

Jeder Webhook führt ein Zustellungsverzeichnis, das du zur Fehlerbehebung einsehen kannst.

1. Gehe zu Einstellungen > Webhooks
2. Klicke auf den Webhook, den du untersuchen möchtest
3. Im Tab Zustellungen siehst du eine Liste mit:

Spalte	Beschreibung
Datum	Exakter Zeitpunkt der Zustellung
Ereignis	Ereignistyp, der die Zustellung ausgelöst hat
Status	HTTP-Antwortcode (200, 500, Timeout usw.)
Dauer	Antwortzeit deines Servers

Klicke auf eine beliebige Zustellung, um die vollständigen Details anzuzeigen: gesendete Header, Payload-Body und Antwort deines Servers.

Wiederholungen und Fehler

Almirant versucht fehlgeschlagene Zustellungen automatisch mit exponentiellem Backoff erneut:

Versuch	Wartezeit vor dem Wiederholungsversuch
1	Sofort
2	1 Minute
3	5 Minuten
4	30 Minuten
5	2 Stunden

Als Fehler gilt, wenn:

• Dein Server mit einem HTTP-Code >= 400 antwortet
• Dein Server nicht innerhalb von 10 Sekunden antwortet (Timeout)
• Keine Verbindung mit deinem Server hergestellt werden kann

Nach 5 fehlgeschlagenen Versuchen wird die Zustellung als fehlgeschlagen markiert und nicht weiter wiederholt. Du kannst sie über das Zustellungsprotokoll manuell erneut senden.

Hinweis

Dein Server sollte so schnell wie möglich mit einem HTTP-Code 2xx (idealerweise 200) antworten. Wenn du eine aufwendige Verarbeitung durchführen musst, nimm den Webhook sofort an und verarbeite die Daten asynchron.

Einen Webhook deaktivieren oder löschen

• Deaktivieren: Verwende in der Webhook-Liste den Schalter, um ihn vorübergehend zu deaktivieren. Die Zustellungen werden pausiert, aber die Konfiguration bleibt erhalten.
• Löschen: Klicke auf das Löschsymbol. Diese Aktion ist nicht umkehrbar und löscht auch das Zustellungsverzeichnis.