Webhook-Endpunkte

Webhook-Endpunkte ermoglichen es dir, HTTP-Callbacks zu empfangen, wenn Events in deiner Organisation auftreten -- zum Beispiel wenn ein Ticket erstellt oder ein Status geandert wird. Du registrierst eine URL, wahlst die Events aus, die du abonnieren mochtest, und Spedy sendet einen signierten POST-Request an deine URL, wenn ein passendes Event ausgelost wird.

Webhook-Endpunkte erfordern ein Pro-Plan-Abonnement.

Unterstuetzte Events

GET /api/v1/webhook-endpoints/events

Gibt die Liste der Event-Typen zurueck, die du abonnieren kannst.

Verfuegbare Events

Payloads

Jede Zustellung hat denselben Umschlag, nur data unterscheidet sich pro Event:

{
  "id": "evt_...",
  "event": "ticket.claimed",
  "timestamp": "2026-09-02T10:00:00.000Z",
  "organizationId": "org_...",
  "data": { }
}

Der gesamte Body wird mit dem Secret des Endpunkts signiert und als X-Spedy-Signature-256: sha256=<hex> gesendet; X-Spedy-Event und X-Spedy-Delivery tragen Eventnamen und Delivery-ID.

data enthaelt IDs und Status, niemals Inhalte. Ein Webhook-Empfaenger steht ausserhalb des Berechtigungsmodells von Spedy -- deshalb verlaesst weder ein Kommentartext noch eine Ticketbeschreibung diesen Kanal. comment.created liefert eine commentId und ein isSecret-Flag; den Kommentar selbst liest du ueber die API mit einem Token, das dafuer auch berechtigt ist.

ticketId ist bei den PR-Events null, wenn aus Branch oder Titel kein Ticket-Key aufloesbar war. pr.opened feuert genau einmal -- beim ersten Webhook, der den Pull-Request-Datensatz anlegt. Der periodische Hintergrund-Sync emittiert bewusst nichts, damit das Verbinden eines Repos mit 200 offenen PRs nicht 200 Events ausloest.

Einen Agenten-Loop wecken

ticket.assigned ist der vorgesehene Weckruf fuer einen Loop, der nicht pollen will: Ticket einem Agenten-User zuweisen, Event empfangen, Loop claimt sofort -- statt auf den naechsten tickets_list { claimable: true }-Tick zu warten. In Kombination mit ticket.claimed / ticket.claim_expired siehst du die Uebergabe zwischen mehreren Loops. Siehe Agenten-Loops.

Webhook-Endpunkte auflisten

GET /api/v1/webhook-endpoints

Berechtigung erforderlich: webhooks:view

Gibt alle Webhook-Endpunkte zurueck, die fuer deine Organisation konfiguriert sind.

Beispiel-Response

[
  {
    "id": "wh_abc123",
    "name": "CI/CD Pipeline",
    "url": "https://ci.example.com/hooks/spedy",
    "events": ["ticket.status_changed", "ticket.created"],
    "isActive": true,
    "createdAt": "2025-06-01T10:00:00Z",
    "updatedAt": "2025-06-01T10:00:00Z"
  }
]

Webhook-Endpunkt erstellen

POST /api/v1/webhook-endpoints

Berechtigung erforderlich: webhooks:manage

Erstellt einen neuen Webhook-Endpunkt. Die Antwort enthaelt ein secret-Feld -- speichere es sicher, da es nur einmal zurueckgegeben wird. Verwende das Secret, um die Signatur eingehender Payloads zu verifizieren.

Request Body

Beispiel-Request

{
  "name": "CI/CD Pipeline",
  "url": "https://ci.example.com/hooks/spedy",
  "events": ["ticket.created", "ticket.status_changed"]
}

Beispiel-Response

{
  "id": "wh_abc123",
  "name": "CI/CD Pipeline",
  "url": "https://ci.example.com/hooks/spedy",
  "events": ["ticket.created", "ticket.status_changed"],
  "isActive": true,
  "secret": "whsec_a1b2c3d4e5...",
  "createdAt": "2025-06-01T10:00:00Z",
  "updatedAt": "2025-06-01T10:00:00Z"
}

Webhook-Endpunkt abrufen

GET /api/v1/webhook-endpoints/{id}

Berechtigung erforderlich: webhooks:view

Gibt Details zu einem bestimmten Webhook-Endpunkt zurueck.

Webhook-Endpunkt aktualisieren

PATCH /api/v1/webhook-endpoints/{id}

Berechtigung erforderlich: webhooks:manage

Aktualisiert den Namen, die URL oder die abonnierten Events eines Webhook-Endpunkts.

Webhook-Endpunkt loeschen

DELETE /api/v1/webhook-endpoints/{id}

Berechtigung erforderlich: webhooks:manage

Gibt 204 No Content zurueck.

Webhook-Endpunkt pingen

POST /api/v1/webhook-endpoints/{id}/ping

Berechtigung erforderlich: webhooks:manage

Sendet einen Test-Ping an die Webhook-URL, um die Erreichbarkeit zu pruefen. Gibt 204 No Content zurueck.

Zustellungen auflisten

GET /api/v1/webhook-endpoints/{id}/deliveries

Berechtigung erforderlich: webhooks:view

Gibt die letzten Zustellversuche fuer einen Webhook-Endpunkt zurueck.

Query-Parameter

Beispiel-Response

[
  {
    "id": "dlv_xyz789",
    "endpointId": "wh_abc123",
    "eventType": "ticket.created",
    "statusCode": 200,
    "success": true,
    "attempt": 1,
    "error": null,
    "createdAt": "2025-06-15T14:30:00Z"
  }
]

Erneut zustellen

POST /api/v1/webhook-endpoints/{id}/deliveries/{deliveryId}/redeliver

Berechtigung erforderlich: webhooks:manage

Sendet eine vorherige Webhook-Zustellung erneut. Gibt 204 No Content zurueck.