Webhooks – API-Referenz

Ereignistypen auflisten

GET/api/v1/event-types

Katalog aller Webhook-Ereignisse mit dem Lese-Scope, den ein Empfänger braucht.

Jeder gültige API-Schlüssel oder OAuth-Token.

Antwort 200

object"list"Pflicht
dataArray<EventType>Pflicht
- typeenumPflicht
  Werte: contact.created, contact.updated, contact.deleted, communication.created, debt.created, debt.updated, debt.phase_changed, debt.overdue, debt.paid, debt.deleted, payment.received, payment.deleted, installment_plan.created, installment_plan.updated, installment_plan.deleted, installment.due, installment.missed, residence_registry_inquiry.created, recommendation.created, letter.sent, letter.delivered, letter.returned, letter.failed, invoice.created, invoice.updated, invoice.finalized, invoice.sent, invoice.partially_paid, invoice.paid, invoice.overdue, invoice.canceled, invoice.deleted, invoice.handed_to_collection, credit_note.finalized, offer.created, offer.sent, offer.accepted, offer.rejected, offer.expired, offer.converted, receipt.created, receipt.processed, receipt.updated, receipt.booked, receipt.deleted, bank_transaction.imported, bank_transaction.matched, project.created, project.updated, project.archived, project.deleted, time_entry.created, time_entry.updated, time_entry.deleted, export.ready, accounting_period.closed, webhook.test
- descriptionstringPflicht
- scopestringPflicht
  Benötigter Lese-Scope

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/event-types' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "type": "contact.created",
      "description": "string",
      "scope": "string"
    }
  ]
}

Alle Ereignisse des Kontos, neueste zuerst – dieselben Nutzlasten wie bei Webhooks. Geeignet für Polling-Trigger (Zapier, Make, n8n). Ereignisse, für die der Schlüssel keinen Lese-Scope hat, werden ausgelassen. Aufbewahrung: verarbeitete Ereignisse 30 Tage (noch nicht zugestellte länger).

Berechtigung: webhooks:read

Query-Parameter

typeenum
Werte: contact.created, contact.updated, contact.deleted, communication.created, debt.created, debt.updated, debt.phase_changed, debt.overdue, debt.paid, debt.deleted, payment.received, payment.deleted, installment_plan.created, installment_plan.updated, installment_plan.deleted, installment.due, installment.missed, residence_registry_inquiry.created, recommendation.created, letter.sent, letter.delivered, letter.returned, letter.failed, invoice.created, invoice.updated, invoice.finalized, invoice.sent, invoice.partially_paid, invoice.paid, invoice.overdue, invoice.canceled, invoice.deleted, invoice.handed_to_collection, credit_note.finalized, offer.created, offer.sent, offer.accepted, offer.rejected, offer.expired, offer.converted, receipt.created, receipt.processed, receipt.updated, receipt.booked, receipt.deleted, bank_transaction.imported, bank_transaction.matched, project.created, project.updated, project.archived, project.deleted, time_entry.created, time_entry.updated, time_entry.deleted, export.ready, accounting_period.closed, webhook.test
limitinteger
Anzahl Einträge (1–100)
1–100 · Standard: 25
cursorstring
`nextCursor` der vorherigen Seite
max. 500 Zeichen

Antwort 200

object"list"Pflicht
dataArray<Event>Pflicht
- idstringPflicht
- object"event"Pflicht
- typeenumPflicht
  Werte: contact.created, contact.updated, contact.deleted, communication.created, debt.created, debt.updated, debt.phase_changed, debt.overdue, debt.paid, debt.deleted, payment.received, payment.deleted, installment_plan.created, installment_plan.updated, installment_plan.deleted, installment.due, installment.missed, residence_registry_inquiry.created, recommendation.created, letter.sent, letter.delivered, letter.returned, letter.failed, invoice.created, invoice.updated, invoice.finalized, invoice.sent, invoice.partially_paid, invoice.paid, invoice.overdue, invoice.canceled, invoice.deleted, invoice.handed_to_collection, credit_note.finalized, offer.created, offer.sent, offer.accepted, offer.rejected, offer.expired, offer.converted, receipt.created, receipt.processed, receipt.updated, receipt.booked, receipt.deleted, bank_transaction.imported, bank_transaction.matched, project.created, project.updated, project.archived, project.deleted, time_entry.created, time_entry.updated, time_entry.deleted, export.ready, accounting_period.closed, webhook.test
- apiVersionstringPflicht
- createdAtstring (date-time)Pflicht
- dataobjectPflicht
  - objectobjectPflicht
    Ressource im Format der REST-API v1
  - previousobject
    Geänderte Felder vorher (nur bei *.updated)
hasMorebooleanPflicht
nextCursorstring | nullPflicht

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/events' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "evt_3kR9xY2mQ7pL0aB4cD1e",
      "object": "event",
      "type": "contact.created",
      "apiVersion": "string",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "data": {
        "object": {},
        "previous": {}
      }
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Ereignis abrufen

GET/api/v1/events/{id}

Berechtigung: webhooks:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200 · Event

idstringPflicht
object"event"Pflicht
typeenumPflicht
Werte: contact.created, contact.updated, contact.deleted, communication.created, debt.created, debt.updated, debt.phase_changed, debt.overdue, debt.paid, debt.deleted, payment.received, payment.deleted, installment_plan.created, installment_plan.updated, installment_plan.deleted, installment.due, installment.missed, residence_registry_inquiry.created, recommendation.created, letter.sent, letter.delivered, letter.returned, letter.failed, invoice.created, invoice.updated, invoice.finalized, invoice.sent, invoice.partially_paid, invoice.paid, invoice.overdue, invoice.canceled, invoice.deleted, invoice.handed_to_collection, credit_note.finalized, offer.created, offer.sent, offer.accepted, offer.rejected, offer.expired, offer.converted, receipt.created, receipt.processed, receipt.updated, receipt.booked, receipt.deleted, bank_transaction.imported, bank_transaction.matched, project.created, project.updated, project.archived, project.deleted, time_entry.created, time_entry.updated, time_entry.deleted, export.ready, accounting_period.closed, webhook.test
apiVersionstringPflicht
createdAtstring (date-time)Pflicht
dataobjectPflicht
- objectobjectPflicht
  Ressource im Format der REST-API v1
- previousobject
  Geänderte Felder vorher (nur bei *.updated)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/events/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "evt_3kR9xY2mQ7pL0aB4cD1e",
  "object": "event",
  "type": "contact.created",
  "apiVersion": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "data": {
    "object": {},
    "previous": {}
  }
}

Zustellprotokoll

GET/api/v1/webhook-deliveries

Zustellungen der letzten 30 Tage, neueste zuerst; mit Antwortstatus und Versuchen.

Berechtigung: webhooks:read

Query-Parameter

endpointIdstring
max. 128 Zeichen
limitinteger
Anzahl Einträge (1–100)
1–100 · Standard: 25
cursorstring
`nextCursor` der vorherigen Seite
max. 500 Zeichen

Antwort 200

object"list"Pflicht
dataArray<WebhookDelivery>Pflicht
- idstringPflicht
- object"webhook_delivery"Pflicht
- endpointIdstringPflicht
- eventIdstringPflicht
- eventTypeenumPflicht
  Werte: contact.created, contact.updated, contact.deleted, communication.created, debt.created, debt.updated, debt.phase_changed, debt.overdue, debt.paid, debt.deleted, payment.received, payment.deleted, installment_plan.created, installment_plan.updated, installment_plan.deleted, installment.due, installment.missed, residence_registry_inquiry.created, recommendation.created, letter.sent, letter.delivered, letter.returned, letter.failed, invoice.created, invoice.updated, invoice.finalized, invoice.sent, invoice.partially_paid, invoice.paid, invoice.overdue, invoice.canceled, invoice.deleted, invoice.handed_to_collection, credit_note.finalized, offer.created, offer.sent, offer.accepted, offer.rejected, offer.expired, offer.converted, receipt.created, receipt.processed, receipt.updated, receipt.booked, receipt.deleted, bank_transaction.imported, bank_transaction.matched, project.created, project.updated, project.archived, project.deleted, time_entry.created, time_entry.updated, time_entry.deleted, export.ready, accounting_period.closed, webhook.test
- status"pending" | "succeeded" | "failed"Pflicht
- testbooleanPflicht
- attemptsintegerPflicht
  -9007199254740991–9007199254740991
- nextAttemptAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- lastAttemptAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- responseStatusinteger | nullPflicht
  -9007199254740991–9007199254740991
- responseBodystring | nullPflicht
  Anfang der Antwort (max. 200 Zeichen; Werte sensibler Header und Tokens entfernt)
- errorstring | nullPflicht
- durationMsinteger | nullPflicht
  -9007199254740991–9007199254740991
- attemptLogArray<object>Pflicht
  Letzte Versuche
  - atstring (date-time)Pflicht
    Zeitpunkt (ISO 8601)
  - responseStatusinteger | nullPflicht
    -9007199254740991–9007199254740991
  - errorstring | nullPflicht
  - durationMsintegerPflicht
    -9007199254740991–9007199254740991
- createdAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
hasMorebooleanPflicht
nextCursorstring | nullPflicht

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/webhook-deliveries' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "webhook_delivery",
      "endpointId": "string",
      "eventId": "string",
      "eventType": "contact.created",
      "status": "pending",
      "test": false,
      "attempts": 0,
      "nextAttemptAt": "2026-11-01T09:30:00.000Z",
      "lastAttemptAt": "2026-11-01T09:30:00.000Z",
      "responseStatus": 0,
      "responseBody": "string",
      "error": "string",
      "durationMs": 0,
      "attemptLog": [
        {
          "at": "2026-11-01T09:30:00.000Z",
          "responseStatus": null,
          "error": "string",
          "durationMs": 0
        }
      ],
      "createdAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Zustellung abrufen

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

Berechtigung: webhooks:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200 · WebhookDelivery

idstringPflicht
object"webhook_delivery"Pflicht
endpointIdstringPflicht
eventIdstringPflicht
eventTypeenumPflicht
Werte: contact.created, contact.updated, contact.deleted, communication.created, debt.created, debt.updated, debt.phase_changed, debt.overdue, debt.paid, debt.deleted, payment.received, payment.deleted, installment_plan.created, installment_plan.updated, installment_plan.deleted, installment.due, installment.missed, residence_registry_inquiry.created, recommendation.created, letter.sent, letter.delivered, letter.returned, letter.failed, invoice.created, invoice.updated, invoice.finalized, invoice.sent, invoice.partially_paid, invoice.paid, invoice.overdue, invoice.canceled, invoice.deleted, invoice.handed_to_collection, credit_note.finalized, offer.created, offer.sent, offer.accepted, offer.rejected, offer.expired, offer.converted, receipt.created, receipt.processed, receipt.updated, receipt.booked, receipt.deleted, bank_transaction.imported, bank_transaction.matched, project.created, project.updated, project.archived, project.deleted, time_entry.created, time_entry.updated, time_entry.deleted, export.ready, accounting_period.closed, webhook.test
status"pending" | "succeeded" | "failed"Pflicht
testbooleanPflicht
attemptsintegerPflicht
-9007199254740991–9007199254740991
nextAttemptAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastAttemptAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
responseStatusinteger | nullPflicht
-9007199254740991–9007199254740991
responseBodystring | nullPflicht
Anfang der Antwort (max. 200 Zeichen; Werte sensibler Header und Tokens entfernt)
errorstring | nullPflicht
durationMsinteger | nullPflicht
-9007199254740991–9007199254740991
attemptLogArray<object>Pflicht
Letzte Versuche
- atstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- responseStatusinteger | nullPflicht
  -9007199254740991–9007199254740991
- errorstring | nullPflicht
- durationMsintegerPflicht
  -9007199254740991–9007199254740991
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/webhook-deliveries/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "object": "webhook_delivery",
  "endpointId": "string",
  "eventId": "string",
  "eventType": "contact.created",
  "status": "pending",
  "test": false,
  "attempts": 0,
  "nextAttemptAt": "2026-11-01T09:30:00.000Z",
  "lastAttemptAt": "2026-11-01T09:30:00.000Z",
  "responseStatus": 0,
  "responseBody": "string",
  "error": "string",
  "durationMs": 0,
  "attemptLog": [
    {
      "at": "2026-11-01T09:30:00.000Z",
      "responseStatus": 0,
      "error": "string",
      "durationMs": 0
    }
  ],
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Zustellung erneut senden

POST/api/v1/webhook-deliveries/{id}/retry

Versucht die Zustellung sofort erneut – auch nach endgültigem Fehlschlag.

Berechtigung: webhooks:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200 · WebhookDelivery

idstringPflicht
object"webhook_delivery"Pflicht
endpointIdstringPflicht
eventIdstringPflicht
eventTypeenumPflicht
Werte: contact.created, contact.updated, contact.deleted, communication.created, debt.created, debt.updated, debt.phase_changed, debt.overdue, debt.paid, debt.deleted, payment.received, payment.deleted, installment_plan.created, installment_plan.updated, installment_plan.deleted, installment.due, installment.missed, residence_registry_inquiry.created, recommendation.created, letter.sent, letter.delivered, letter.returned, letter.failed, invoice.created, invoice.updated, invoice.finalized, invoice.sent, invoice.partially_paid, invoice.paid, invoice.overdue, invoice.canceled, invoice.deleted, invoice.handed_to_collection, credit_note.finalized, offer.created, offer.sent, offer.accepted, offer.rejected, offer.expired, offer.converted, receipt.created, receipt.processed, receipt.updated, receipt.booked, receipt.deleted, bank_transaction.imported, bank_transaction.matched, project.created, project.updated, project.archived, project.deleted, time_entry.created, time_entry.updated, time_entry.deleted, export.ready, accounting_period.closed, webhook.test
status"pending" | "succeeded" | "failed"Pflicht
testbooleanPflicht
attemptsintegerPflicht
-9007199254740991–9007199254740991
nextAttemptAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastAttemptAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
responseStatusinteger | nullPflicht
-9007199254740991–9007199254740991
responseBodystring | nullPflicht
Anfang der Antwort (max. 200 Zeichen; Werte sensibler Header und Tokens entfernt)
errorstring | nullPflicht
durationMsinteger | nullPflicht
-9007199254740991–9007199254740991
attemptLogArray<object>Pflicht
Letzte Versuche
- atstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- responseStatusinteger | nullPflicht
  -9007199254740991–9007199254740991
- errorstring | nullPflicht
- durationMsintegerPflicht
  -9007199254740991–9007199254740991
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/webhook-deliveries/ID/retry' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "object": "webhook_delivery",
  "endpointId": "string",
  "eventId": "string",
  "eventType": "contact.created",
  "status": "pending",
  "test": false,
  "attempts": 0,
  "nextAttemptAt": "2026-11-01T09:30:00.000Z",
  "lastAttemptAt": "2026-11-01T09:30:00.000Z",
  "responseStatus": 0,
  "responseBody": "string",
  "error": "string",
  "durationMs": 0,
  "attemptLog": [
    {
      "at": "2026-11-01T09:30:00.000Z",
      "responseStatus": 0,
      "error": "string",
      "durationMs": 0
    }
  ],
  "createdAt": "2026-11-01T09:30:00.000Z"
}

Webhook-Endpunkte auflisten

GET/api/v1/webhook-endpoints

Berechtigung: webhooks:read

Query-Parameter

limitinteger
Anzahl Einträge (1–100)
1–100 · Standard: 25
cursorstring
`nextCursor` der vorherigen Seite
max. 500 Zeichen

Antwort 200

object"list"Pflicht
dataArray<WebhookEndpoint>Pflicht
- idstringPflicht
- object"webhook_endpoint"Pflicht
- urlstringPflicht
- descriptionstringPflicht
- eventsArray<enum | "*">Pflicht
  Ereignistyp oder "*" für alle
- payloadFormat"json" | "text"Pflicht
  Content-Type der Zustellung: json = application/json (Standard), text = text/plain mit identischem Body (für Plattformen, die nur so den Rohtext zur Signaturprüfung liefern, z. B. Make)
- activebooleanPflicht
- disabledReasonstring | nullPflicht
  Grund der automatischen Deaktivierung
- disabledAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- secretHintstringPflicht
  Anfang des Signaturgeheimnisses
- createdVia"session" | "api_key" | "oauth"Pflicht
- consecutiveFailuresintegerPflicht
  -9007199254740991–9007199254740991
- failingSincestring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- lastDeliveryAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- lastDeliveryStatus"succeeded" | "failed" | nullPflicht
- createdAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- updatedAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
hasMorebooleanPflicht
nextCursorstring | nullPflicht

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/webhook-endpoints' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "object": "webhook_endpoint",
      "url": "string",
      "description": "string",
      "events": [
        "contact.created"
      ],
      "payloadFormat": "json",
      "active": false,
      "disabledReason": "string",
      "disabledAt": "2026-11-01T09:30:00.000Z",
      "secretHint": "string",
      "createdVia": "session",
      "consecutiveFailures": 0,
      "failingSince": "2026-11-01T09:30:00.000Z",
      "lastDeliveryAt": "2026-11-01T09:30:00.000Z",
      "lastDeliveryStatus": "succeeded",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Webhook-Endpunkt anlegen

POST/api/v1/webhook-endpoints

DebtFlow sendet abonnierte Ereignisse per POST (JSON Event) an die HTTPS-URL. Jede Anfrage ist signiert: DebtFlow-Signature: t=<Unix-Zeit>,v1=<HMAC-SHA256(secret, "<t>.<Body>") hex> (gleich auch als X-DebtFlow-Signature). Das Geheimnis (secret) steht nur in dieser Antwort. Per API-Schlüssel angelegte Endpunkte erhalten nur Ereignisse, deren Lese-Scope der Schlüssel hat.

Berechtigung: webhooks:write

Body (JSON) · WebhookEndpointCreate

urlstring (uri)Pflicht
HTTPS-Adresse, die POST-Anfragen annimmt
max. 2048 Zeichen
eventsArray<enum | "*">Pflicht
Ereignistyp oder "*" für alle
descriptionstring
max. 200 Zeichen
payloadFormat"json" | "text"
Standard json
activeboolean

Antwort 201 · WebhookEndpointCreated

idstringPflicht
object"webhook_endpoint"Pflicht
urlstringPflicht
descriptionstringPflicht
eventsArray<enum | "*">Pflicht
Ereignistyp oder "*" für alle
payloadFormat"json" | "text"Pflicht
Content-Type der Zustellung: json = application/json (Standard), text = text/plain mit identischem Body (für Plattformen, die nur so den Rohtext zur Signaturprüfung liefern, z. B. Make)
activebooleanPflicht
disabledReasonstring | nullPflicht
Grund der automatischen Deaktivierung
disabledAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
secretHintstringPflicht
Anfang des Signaturgeheimnisses
createdVia"session" | "api_key" | "oauth"Pflicht
consecutiveFailuresintegerPflicht
-9007199254740991–9007199254740991
failingSincestring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastDeliveryAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastDeliveryStatus"succeeded" | "failed" | nullPflicht
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
secretstringPflicht
Signaturgeheimnis (whsec_…) – nur in dieser Antwort

Mögliche Fehler: 400, 401, 403, 409, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/webhook-endpoints' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com",
  "events": [
    "contact.created"
  ],
  "description": "string",
  "payloadFormat": "json",
  "active": false
}'

Antwort 201

{
  "id": "string",
  "object": "webhook_endpoint",
  "url": "string",
  "description": "string",
  "events": [
    "contact.created"
  ],
  "payloadFormat": "json",
  "active": false,
  "disabledReason": "string",
  "disabledAt": "2026-11-01T09:30:00.000Z",
  "secretHint": "string",
  "createdVia": "session",
  "consecutiveFailures": 0,
  "failingSince": "2026-11-01T09:30:00.000Z",
  "lastDeliveryAt": "2026-11-01T09:30:00.000Z",
  "lastDeliveryStatus": "succeeded",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z",
  "secret": "string"
}

Webhook-Endpunkt abrufen

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

Berechtigung: webhooks:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200 · WebhookEndpoint

idstringPflicht
object"webhook_endpoint"Pflicht
urlstringPflicht
descriptionstringPflicht
eventsArray<enum | "*">Pflicht
Ereignistyp oder "*" für alle
payloadFormat"json" | "text"Pflicht
Content-Type der Zustellung: json = application/json (Standard), text = text/plain mit identischem Body (für Plattformen, die nur so den Rohtext zur Signaturprüfung liefern, z. B. Make)
activebooleanPflicht
disabledReasonstring | nullPflicht
Grund der automatischen Deaktivierung
disabledAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
secretHintstringPflicht
Anfang des Signaturgeheimnisses
createdVia"session" | "api_key" | "oauth"Pflicht
consecutiveFailuresintegerPflicht
-9007199254740991–9007199254740991
failingSincestring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastDeliveryAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastDeliveryStatus"succeeded" | "failed" | nullPflicht
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/webhook-endpoints/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "object": "webhook_endpoint",
  "url": "string",
  "description": "string",
  "events": [
    "contact.created"
  ],
  "payloadFormat": "json",
  "active": false,
  "disabledReason": "string",
  "disabledAt": "2026-11-01T09:30:00.000Z",
  "secretHint": "string",
  "createdVia": "session",
  "consecutiveFailures": 0,
  "failingSince": "2026-11-01T09:30:00.000Z",
  "lastDeliveryAt": "2026-11-01T09:30:00.000Z",
  "lastDeliveryStatus": "succeeded",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Webhook-Endpunkt ändern

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

active: true aktiviert einen automatisch deaktivierten Endpunkt wieder und setzt den Fehlerzähler zurück. Die Ziel-URL eines Endpunkts lässt sich nur mit allen Lese-Berechtigungen ändern, mit denen er angelegt wurde (sonst 403 insufficient_scope).

Berechtigung: webhooks:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Body (JSON) · WebhookEndpointUpdate

urlstring (uri)
HTTPS-Adresse, die POST-Anfragen annimmt
max. 2048 Zeichen
eventsArray<enum | "*">
Ereignistyp oder "*" für alle
descriptionstring
max. 200 Zeichen
payloadFormat"json" | "text"
activeboolean
true aktiviert wieder (setzt den Fehlerzähler zurück)

Antwort 200 · WebhookEndpoint

idstringPflicht
object"webhook_endpoint"Pflicht
urlstringPflicht
descriptionstringPflicht
eventsArray<enum | "*">Pflicht
Ereignistyp oder "*" für alle
payloadFormat"json" | "text"Pflicht
Content-Type der Zustellung: json = application/json (Standard), text = text/plain mit identischem Body (für Plattformen, die nur so den Rohtext zur Signaturprüfung liefern, z. B. Make)
activebooleanPflicht
disabledReasonstring | nullPflicht
Grund der automatischen Deaktivierung
disabledAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
secretHintstringPflicht
Anfang des Signaturgeheimnisses
createdVia"session" | "api_key" | "oauth"Pflicht
consecutiveFailuresintegerPflicht
-9007199254740991–9007199254740991
failingSincestring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastDeliveryAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastDeliveryStatus"succeeded" | "failed" | nullPflicht
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/webhook-endpoints/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com",
  "events": [
    "contact.created"
  ],
  "description": "string",
  "payloadFormat": "json",
  "active": false
}'

Antwort 200

{
  "id": "string",
  "object": "webhook_endpoint",
  "url": "string",
  "description": "string",
  "events": [
    "contact.created"
  ],
  "payloadFormat": "json",
  "active": false,
  "disabledReason": "string",
  "disabledAt": "2026-11-01T09:30:00.000Z",
  "secretHint": "string",
  "createdVia": "session",
  "consecutiveFailures": 0,
  "failingSince": "2026-11-01T09:30:00.000Z",
  "lastDeliveryAt": "2026-11-01T09:30:00.000Z",
  "lastDeliveryStatus": "succeeded",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Webhook-Endpunkt löschen

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

Löscht auch das Zustellprotokoll des Endpunkts.

Berechtigung: webhooks:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 204

Erfolg, keine Antwort

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/webhook-endpoints/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Signaturgeheimnis erneuern

POST/api/v1/webhook-endpoints/{id}/rotate-secret

Das alte Geheimnis ist sofort ungültig. Das neue steht nur in dieser Antwort. Nur mit allen Lese-Berechtigungen, mit denen der Endpunkt angelegt wurde (sonst 403 insufficient_scope).

Berechtigung: webhooks:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200 · WebhookEndpointCreated

idstringPflicht
object"webhook_endpoint"Pflicht
urlstringPflicht
descriptionstringPflicht
eventsArray<enum | "*">Pflicht
Ereignistyp oder "*" für alle
payloadFormat"json" | "text"Pflicht
Content-Type der Zustellung: json = application/json (Standard), text = text/plain mit identischem Body (für Plattformen, die nur so den Rohtext zur Signaturprüfung liefern, z. B. Make)
activebooleanPflicht
disabledReasonstring | nullPflicht
Grund der automatischen Deaktivierung
disabledAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
secretHintstringPflicht
Anfang des Signaturgeheimnisses
createdVia"session" | "api_key" | "oauth"Pflicht
consecutiveFailuresintegerPflicht
-9007199254740991–9007199254740991
failingSincestring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastDeliveryAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastDeliveryStatus"succeeded" | "failed" | nullPflicht
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
secretstringPflicht
Signaturgeheimnis (whsec_…) – nur in dieser Antwort

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/webhook-endpoints/ID/rotate-secret' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "object": "webhook_endpoint",
  "url": "string",
  "description": "string",
  "events": [
    "contact.created"
  ],
  "payloadFormat": "json",
  "active": false,
  "disabledReason": "string",
  "disabledAt": "2026-11-01T09:30:00.000Z",
  "secretHint": "string",
  "createdVia": "session",
  "consecutiveFailures": 0,
  "failingSince": "2026-11-01T09:30:00.000Z",
  "lastDeliveryAt": "2026-11-01T09:30:00.000Z",
  "lastDeliveryStatus": "succeeded",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z",
  "secret": "string"
}

Testereignis senden

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

Sendet sofort ein signiertes webhook.test-Ereignis an diesen Endpunkt und liefert das Ergebnis. Ohne Wiederholung; zählt nicht für die automatische Deaktivierung.

Berechtigung: webhooks:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200 · WebhookDelivery

idstringPflicht
object"webhook_delivery"Pflicht
endpointIdstringPflicht
eventIdstringPflicht
eventTypeenumPflicht
Werte: contact.created, contact.updated, contact.deleted, communication.created, debt.created, debt.updated, debt.phase_changed, debt.overdue, debt.paid, debt.deleted, payment.received, payment.deleted, installment_plan.created, installment_plan.updated, installment_plan.deleted, installment.due, installment.missed, residence_registry_inquiry.created, recommendation.created, letter.sent, letter.delivered, letter.returned, letter.failed, invoice.created, invoice.updated, invoice.finalized, invoice.sent, invoice.partially_paid, invoice.paid, invoice.overdue, invoice.canceled, invoice.deleted, invoice.handed_to_collection, credit_note.finalized, offer.created, offer.sent, offer.accepted, offer.rejected, offer.expired, offer.converted, receipt.created, receipt.processed, receipt.updated, receipt.booked, receipt.deleted, bank_transaction.imported, bank_transaction.matched, project.created, project.updated, project.archived, project.deleted, time_entry.created, time_entry.updated, time_entry.deleted, export.ready, accounting_period.closed, webhook.test
status"pending" | "succeeded" | "failed"Pflicht
testbooleanPflicht
attemptsintegerPflicht
-9007199254740991–9007199254740991
nextAttemptAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
lastAttemptAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
responseStatusinteger | nullPflicht
-9007199254740991–9007199254740991
responseBodystring | nullPflicht
Anfang der Antwort (max. 200 Zeichen; Werte sensibler Header und Tokens entfernt)
errorstring | nullPflicht
durationMsinteger | nullPflicht
-9007199254740991–9007199254740991
attemptLogArray<object>Pflicht
Letzte Versuche
- atstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- responseStatusinteger | nullPflicht
  -9007199254740991–9007199254740991
- errorstring | nullPflicht
- durationMsintegerPflicht
  -9007199254740991–9007199254740991
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/webhook-endpoints/ID/test' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "object": "webhook_delivery",
  "endpointId": "string",
  "eventId": "string",
  "eventType": "contact.created",
  "status": "pending",
  "test": false,
  "attempts": 0,
  "nextAttemptAt": "2026-11-01T09:30:00.000Z",
  "lastAttemptAt": "2026-11-01T09:30:00.000Z",
  "responseStatus": 0,
  "responseBody": "string",
  "error": "string",
  "durationMs": 0,
  "attemptLog": [
    {
      "at": "2026-11-01T09:30:00.000Z",
      "responseStatus": 0,
      "error": "string",
      "durationMs": 0
    }
  ],
  "createdAt": "2026-11-01T09:30:00.000Z"
}