Webhook-Endpunkte

Webhook-Endpunkte auflisten#

Alle Webhook-Endpunkte Ihres Unternehmens, älteste zuerst. Das Secret ist nie enthalten.

Scope

webhooks.manage — Webhook-Endpunkte verwalten

Beispielanfrage

curl "https://app.klantly.com/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'webhook-endpoints');

$data = json_decode((string) $response->getBody(), true)['data'];

const response = await fetch('https://app.klantly.com/api/v1/webhook-endpoints', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/webhook-endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwort 200

Die Antwort ist eine Liste mit Cursor-Paginierung: data enthält die Objekte, meta die Paginierung.

{
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "01j7zr8m2k4n6p8r0t2v4w6y8a",
      "url": "https://example.com/webhooks/klantly",
      "description": "Boekhouding",
      "events": [
        "customer.created",
        "deal.won"
      ],
      "status": "active",
      "disabled_reason": null,
      "disabled_at": null,
      "previous_secret_expires_at": null,
      "last_success_at": "2026-09-14T10:15:02Z",
      "last_failure_at": null,
      "created_at": "2026-09-14T10:15:00Z",
      "updated_at": "2026-09-14T10:15:00Z"
    }
  ],
  "meta": {
    "limit": 50,
    "next_cursor": "eyJpZCI6IjlkM2Y2YzFlIn0",
    "prev_cursor": null
  }
}

Mögliche Fehler

• 403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Webhook-Endpunkt abrufen#

Ein Endpunkt nach ID, mit Status und dem Zeitpunkt der letzten erfolgreichen und fehlgeschlagenen Zustellung.

Scope

webhooks.manage — Webhook-Endpunkte verwalten

Pfadparameter

Beispielanfrage

curl "https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('GET', 'webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];

const response = await fetch('https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();

import os

import requests

response = requests.get(
    "https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwort 200

{
  "data": {
    "object": "webhook_endpoint",
    "id": "01j7zr8m2k4n6p8r0t2v4w6y8a",
    "url": "https://example.com/webhooks/klantly",
    "description": "Boekhouding",
    "events": [
      "customer.created",
      "deal.won"
    ],
    "status": "active",
    "disabled_reason": null,
    "disabled_at": null,
    "previous_secret_expires_at": null,
    "last_success_at": "2026-09-14T10:15:02Z",
    "last_failure_at": null,
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mögliche Fehler

• 403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
• 404 not_found — Nicht gefunden.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Webhook-Endpunkt erstellen#

Registriert eine https-Adresse, die Events empfängt. Die Antwort enthält das Secret zum Prüfen der Signatur: Speichern Sie es sofort, Sie sehen es danach nicht mehr. Sie können nur Events zu Daten wählen, auf die Ihr Schlüssel Leserechte hat; * bedeutet alle Events darunter, auch künftige. Höchstens 10 Endpunkte pro Unternehmen.

Scope

webhooks.manage — Webhook-Endpunkte verwalten

Body (JSON)

Beispielanfrage

curl -X POST "https://app.klantly.com/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "url": "https://example.com/webhooks/klantly",
  "description": "Boekhouding",
  "events": [
    "customer.created",
    "deal.won"
  ]
}'

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'webhook-endpoints', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'url' => 'https://example.com/webhooks/klantly',
        'description' => 'Boekhouding',
        'events' => [
            0 => 'customer.created',
            1 => 'deal.won',
        ],
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

const response = await fetch('https://app.klantly.com/api/v1/webhook-endpoints', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "url": "https://example.com/webhooks/klantly",
  "description": "Boekhouding",
  "events": [
    "customer.created",
    "deal.won"
  ]
}),
});

const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/webhook-endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "url": "https://example.com/webhooks/klantly",
        "description": "Boekhouding",
        "events": [
            "customer.created",
            "deal.won"
        ]
    },
)
data = response.json()["data"]

Antwort 201

{
  "data": {
    "object": "webhook_endpoint",
    "id": "01j7zr8m2k4n6p8r0t2v4w6y8a",
    "url": "https://example.com/webhooks/klantly",
    "description": "Boekhouding",
    "events": [
      "customer.created",
      "deal.won"
    ],
    "status": "active",
    "disabled_reason": null,
    "disabled_at": null,
    "previous_secret_expires_at": null,
    "last_success_at": "2026-09-14T10:15:02Z",
    "last_failure_at": null,
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  }
}

Mögliche Fehler

• 403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
• 422 validation_failed — Die Eingabe ist ungültig.
• 422 unknown_field — Die Eingabe enthält ein unbekanntes Feld.
• 415 unsupported_media_type — Dieses Format wird nicht unterstützt.
• 413 payload_too_large — Der Body der Anfrage ist zu groß.
• 403 limit_reached — Das Limit des Abonnements ist erreicht.
• 422 idempotency_key_reused — Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.
• 409 idempotency_in_progress — Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Webhook-Endpunkt bearbeiten#

Ändert nur die Felder, die Sie mitsenden. Mit status schalten Sie den Endpunkt aus oder wieder ein; das Wiedereinschalten setzt den Fehlerzähler zurück. Wer die Events neu wählt, bestimmt, was der Endpunkt sehen darf: nie mehr als dieser Schlüssel. Jede Änderung (auch das Ausschalten oder eine andere url) erfordert einen Schlüssel, der alles lesen kann, was der Endpunkt jetzt erhält; sonst erhalten Sie 403 insufficient_scope.

Scope

webhooks.manage — Webhook-Endpunkte verwalten

Pfadparameter

Body (JSON)

Beispielanfrage

curl -X PATCH "https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "events": [
    "*"
  ],
  "status": "active"
}'

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('PATCH', 'webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', [
    'json' => [
        'events' => [
            0 => '*',
        ],
        'status' => 'active',
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

const response = await fetch('https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "events": [
    "*"
  ],
  "status": "active"
}),
});

const { data } = await response.json();

import os

import requests

response = requests.patch(
    "https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
    json={
        "events": [
            "*"
        ],
        "status": "active"
    },
)
data = response.json()["data"]

Antwort 200

{
  "data": {
    "object": "webhook_endpoint",
    "id": "01j7zr8m2k4n6p8r0t2v4w6y8a",
    "url": "https://example.com/webhooks/klantly",
    "description": "Boekhouding",
    "events": [
      "customer.created",
      "deal.won"
    ],
    "status": "active",
    "disabled_reason": null,
    "disabled_at": null,
    "previous_secret_expires_at": null,
    "last_success_at": "2026-09-14T10:15:02Z",
    "last_failure_at": null,
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z"
  }
}

Mögliche Fehler

• 403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
• 422 validation_failed — Die Eingabe ist ungültig.
• 422 unknown_field — Die Eingabe enthält ein unbekanntes Feld.
• 415 unsupported_media_type — Dieses Format wird nicht unterstützt.
• 413 payload_too_large — Der Body der Anfrage ist zu groß.
• 404 not_found — Nicht gefunden.
• 412 precondition_failed — Der Datensatz wurde inzwischen geändert.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Webhook-Endpunkt löschen#

Löscht den Endpunkt. Events, die noch unterwegs sind, werden nicht mehr zugestellt. Erfordert einen Schlüssel, der alles lesen kann, was der Endpunkt erhält.

Scope

webhooks.manage — Webhook-Endpunkte verwalten

Pfadparameter

Beispielanfrage

curl -X DELETE "https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('DELETE', 'webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70');

$data = json_decode((string) $response->getBody(), true)['data'];

const response = await fetch('https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();

import os

import requests

response = requests.delete(
    "https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwort 200

{
  "data": {
    "object": "note",
    "id": "9d3f7b41-2d6f-4e8c-9b3a-4f5d6e7a8b92",
    "deleted": true
  }
}

Mögliche Fehler

• 403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
• 404 not_found — Nicht gefunden.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Testnachricht senden#

Sendet das Event ping sofort an den Endpunkt, auch wenn er deaktiviert ist, und gibt den Zustellversuch zurück. Eine Testnachricht wird nicht wiederholt.

Scope

webhooks.manage — Webhook-Endpunkte verwalten

Pfadparameter

Beispielanfrage

curl -X POST "https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/test" \
  -H "Authorization: Bearer $KLANTLY_API_KEY"

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/test');

$data = json_decode((string) $response->getBody(), true)['data'];

const response = await fetch('https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
  },
});

const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/test",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
    },
)
data = response.json()["data"]

Antwort 200

{
  "data": {
    "object": "webhook_delivery",
    "id": "whd_0p5t7j31a2e4gm",
    "webhook_endpoint_id": "01j7zr8m2k4n6p8r0t2v4w6y8a",
    "event_id": "evt_01j7zs1a2b3c4d5e6f7g8h9j0k",
    "event_type": "ping",
    "attempt": 1,
    "status": "succeeded",
    "response_status": 200,
    "error": null,
    "duration_ms": 184,
    "created_at": "2026-09-14T10:15:00Z"
  }
}

Mögliche Fehler

• 403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
• 404 not_found — Nicht gefunden.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Secret erneuern#

Erstellt ein neues Secret und gibt es einmalig zurück. Während der Überlappung signiert Klantly mit dem alten und dem neuen Secret, sodass Ihr Empfänger ohne Unterbrechung umstellen kann. Erfordert einen Schlüssel, der alles lesen kann, was der Endpunkt erhält; sonst erhalten Sie 403 insufficient_scope.

Scope

webhooks.manage — Webhook-Endpunkte verwalten

Pfadparameter

Body (JSON)

Beispielanfrage

curl -X POST "https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/rotate-secret" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{
  "overlap_hours": 24
}'

$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://app.klantly.com/api/v1/',
    'headers' => ['Authorization' => 'Bearer ' . getenv('KLANTLY_API_KEY')],
]);

$response = $client->request('POST', 'webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/rotate-secret', [
    'headers' => [
        'Idempotency-Key' => '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
    ],
    'json' => [
        'overlap_hours' => 24,
    ],
]);

$data = json_decode((string) $response->getBody(), true)['data'];

const response = await fetch('https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/rotate-secret', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KLANTLY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': '6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f',
  },
  body: JSON.stringify({
  "overlap_hours": 24
}),
});

const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://app.klantly.com/api/v1/webhook-endpoints/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70/rotate-secret",
    headers={
        "Authorization": f"Bearer {os.environ['KLANTLY_API_KEY']}",
        "Idempotency-Key": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    },
    json={
        "overlap_hours": 24
    },
)
data = response.json()["data"]

Antwort 200

{
  "data": {
    "object": "webhook_endpoint",
    "id": "01j7zr8m2k4n6p8r0t2v4w6y8a",
    "url": "https://example.com/webhooks/klantly",
    "description": "Boekhouding",
    "events": [
      "customer.created",
      "deal.won"
    ],
    "status": "active",
    "disabled_reason": null,
    "disabled_at": null,
    "previous_secret_expires_at": null,
    "last_success_at": "2026-09-14T10:15:02Z",
    "last_failure_at": null,
    "created_at": "2026-09-14T10:15:00Z",
    "updated_at": "2026-09-14T10:15:00Z",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  }
}

Mögliche Fehler

• 403 insufficient_scope — Dieser API-Schlüssel hat keinen Zugriff auf diese Aktion.
• 422 validation_failed — Die Eingabe ist ungültig.
• 422 unknown_field — Die Eingabe enthält ein unbekanntes Feld.
• 415 unsupported_media_type — Dieses Format wird nicht unterstützt.
• 413 payload_too_large — Der Body der Anfrage ist zu groß.
• 404 not_found — Nicht gefunden.
• 422 idempotency_key_reused — Dieser Idempotency-Key wurde bereits für eine andere Anfrage verwendet.
• 409 idempotency_in_progress — Eine Anfrage mit diesem Idempotency-Key wird noch verarbeitet.

Zusätzlich kann jeder Endpunkt die allgemeinen Fehler zurückgeben, etwa einen ungültigen Schlüssel oder ein erreichtes Limit. Alle Fehlercodes ansehen.

Das Objekt#

Alle Felder sind immer vorhanden; ein Feld ohne Wert ist null.