Zum Inhalt springen
DebtFlow

Webhooks

Webhook endpoints, deliveries and events.

List event types

GET/api/v1/event-types

Catalogue of all webhook events with the read scope a receiver needs.

Any valid API key or OAuth token.

Response 200

  • object"list"required
  • dataArray<EventType>required
    • typeenumrequired
      Values: 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, payment.refunded, payment.reversed, 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
    • descriptionstringrequired
    • scopestringrequired
      Required read scope

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/event-types' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "object": "list",
  "data": [
    {
      "type": "contact.created",
      "description": "string",
      "scope": "string"
    }
  ]
}

List events

GET/api/v1/events

All events of the account, newest first – the same payloads as for webhooks. Suitable for polling triggers (Zapier, Make, n8n). Events for which the key has no read scope are omitted. Retention: processed events 30 days (events not yet delivered longer).

Permission: webhooks:read

Query parameters

  • typeenum
    Values: 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, payment.refunded, payment.reversed, 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
    Number of entries (1–100)
    1–100 · Default: 25
  • cursorstring
    `nextCursor` of the previous page
    max. 500 characters

Response 200

  • object"list"required
  • dataArray<Event>required
    • idstringrequired
    • object"event"required
    • typeenumrequired
      Values: 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, payment.refunded, payment.reversed, 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
    • apiVersionstringrequired
    • createdAtstring (date-time)required
    • dataobjectrequired
      • objectobjectrequired
        Resource in REST API v1 format
      • previousobject
        Previous values of changed fields (only for *.updated)
  • hasMorebooleanrequired
  • nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/events' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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"
}

Retrieve event

GET/api/v1/events/{id}

Permission: webhooks:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · Event

  • idstringrequired
  • object"event"required
  • typeenumrequired
    Values: 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, payment.refunded, payment.reversed, 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
  • apiVersionstringrequired
  • createdAtstring (date-time)required
  • dataobjectrequired
    • objectobjectrequired
      Resource in REST API v1 format
    • previousobject
      Previous values of changed fields (only for *.updated)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/events/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 200
{
  "id": "evt_3kR9xY2mQ7pL0aB4cD1e",
  "object": "event",
  "type": "contact.created",
  "apiVersion": "string",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "data": {
    "object": {},
    "previous": {}
  }
}

Delivery log

GET/api/v1/webhook-deliveries

Deliveries from the last 30 days, newest first; with response status and attempts.

Permission: webhooks:read

Query parameters

  • endpointIdstring
    max. 128 characters
  • limitinteger
    Number of entries (1–100)
    1–100 · Default: 25
  • cursorstring
    `nextCursor` of the previous page
    max. 500 characters

Response 200

  • object"list"required
  • dataArray<WebhookDelivery>required
    • idstringrequired
    • object"webhook_delivery"required
    • endpointIdstringrequired
    • eventIdstringrequired
    • eventTypeenumrequired
      Values: 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, payment.refunded, payment.reversed, 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"required
    • testbooleanrequired
    • attemptsintegerrequired
      -9007199254740991–9007199254740991
    • nextAttemptAtstring (date-time) | nullrequired
      Timestamp (ISO 8601)
    • lastAttemptAtstring (date-time) | nullrequired
      Timestamp (ISO 8601)
    • responseStatusinteger | nullrequired
      -9007199254740991–9007199254740991
    • responseBodystring | nullrequired
      Start of the response (max. 200 characters; values of sensitive headers and tokens removed)
    • errorstring | nullrequired
    • durationMsinteger | nullrequired
      -9007199254740991–9007199254740991
    • attemptLogArray<object>required
      Recent attempts
      • atstring (date-time)required
        Timestamp (ISO 8601)
      • responseStatusinteger | nullrequired
        -9007199254740991–9007199254740991
      • errorstring | nullrequired
      • durationMsintegerrequired
        -9007199254740991–9007199254740991
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)
  • hasMorebooleanrequired
  • nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/webhook-deliveries' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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"
}

Retrieve delivery

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

Permission: webhooks:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · WebhookDelivery

  • idstringrequired
  • object"webhook_delivery"required
  • endpointIdstringrequired
  • eventIdstringrequired
  • eventTypeenumrequired
    Values: 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, payment.refunded, payment.reversed, 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"required
  • testbooleanrequired
  • attemptsintegerrequired
    -9007199254740991–9007199254740991
  • nextAttemptAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastAttemptAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • responseStatusinteger | nullrequired
    -9007199254740991–9007199254740991
  • responseBodystring | nullrequired
    Start of the response (max. 200 characters; values of sensitive headers and tokens removed)
  • errorstring | nullrequired
  • durationMsinteger | nullrequired
    -9007199254740991–9007199254740991
  • attemptLogArray<object>required
    Recent attempts
    • atstring (date-time)required
      Timestamp (ISO 8601)
    • responseStatusinteger | nullrequired
      -9007199254740991–9007199254740991
    • errorstring | nullrequired
    • durationMsintegerrequired
      -9007199254740991–9007199254740991
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/webhook-deliveries/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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"
}

Retry delivery

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

Retries the delivery immediately – even after it has finally failed.

Permission: webhooks:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · WebhookDelivery

  • idstringrequired
  • object"webhook_delivery"required
  • endpointIdstringrequired
  • eventIdstringrequired
  • eventTypeenumrequired
    Values: 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, payment.refunded, payment.reversed, 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"required
  • testbooleanrequired
  • attemptsintegerrequired
    -9007199254740991–9007199254740991
  • nextAttemptAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastAttemptAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • responseStatusinteger | nullrequired
    -9007199254740991–9007199254740991
  • responseBodystring | nullrequired
    Start of the response (max. 200 characters; values of sensitive headers and tokens removed)
  • errorstring | nullrequired
  • durationMsinteger | nullrequired
    -9007199254740991–9007199254740991
  • attemptLogArray<object>required
    Recent attempts
    • atstring (date-time)required
      Timestamp (ISO 8601)
    • responseStatusinteger | nullrequired
      -9007199254740991–9007199254740991
    • errorstring | nullrequired
    • durationMsintegerrequired
      -9007199254740991–9007199254740991
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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"
Response 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"
}

List webhook endpoints

GET/api/v1/webhook-endpoints

Permission: webhooks:read

Query parameters

  • limitinteger
    Number of entries (1–100)
    1–100 · Default: 25
  • cursorstring
    `nextCursor` of the previous page
    max. 500 characters

Response 200

  • object"list"required
  • dataArray<WebhookEndpoint>required
    • idstringrequired
    • object"webhook_endpoint"required
    • urlstringrequired
    • descriptionstringrequired
    • eventsArray<enum | "*">required
      Event type or "*" for all
    • payloadFormat"json" | "text"required
      Content-Type of the delivery: json = application/json (default), text = text/plain with an identical body (for platforms that only provide the raw text for signature verification this way, e.g. Make)
    • activebooleanrequired
    • disabledReasonstring | nullrequired
      Reason for automatic deactivation
    • disabledAtstring (date-time) | nullrequired
      Timestamp (ISO 8601)
    • secretHintstringrequired
      First characters of the signing secret
    • createdVia"session" | "api_key" | "oauth"required
    • consecutiveFailuresintegerrequired
      -9007199254740991–9007199254740991
    • failingSincestring (date-time) | nullrequired
      Timestamp (ISO 8601)
    • lastDeliveryAtstring (date-time) | nullrequired
      Timestamp (ISO 8601)
    • lastDeliveryStatus"succeeded" | "failed" | nullrequired
    • createdAtstring (date-time)required
      Timestamp (ISO 8601)
    • updatedAtstring (date-time)required
      Timestamp (ISO 8601)
  • hasMorebooleanrequired
  • nextCursorstring | nullrequired

Possible errors: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/webhook-endpoints' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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"
}

Create webhook endpoint

POST/api/v1/webhook-endpoints

DebtFlow sends subscribed events via POST (JSON Event) to the HTTPS URL. Every request is signed: DebtFlow-Signature: t=<Unix-Zeit>,v1=<HMAC-SHA256(secret, "<t>.<Body>") hex> (also sent identically as X-DebtFlow-Signature). The secret (secret) is only included in this response. Endpoints created with an API key only receive events for which the key has the read scope.

Permission: webhooks:write

Body (JSON) · WebhookEndpointCreate

  • urlstring (uri)required
    HTTPS address that accepts POST requests
    max. 2048 characters
  • eventsArray<enum | "*">required
    Event type or "*" for all
  • descriptionstring
    max. 200 characters
  • payloadFormat"json" | "text"
    Default json
  • activeboolean

Response 201 · WebhookEndpointCreated

  • idstringrequired
  • object"webhook_endpoint"required
  • urlstringrequired
  • descriptionstringrequired
  • eventsArray<enum | "*">required
    Event type or "*" for all
  • payloadFormat"json" | "text"required
    Content-Type of the delivery: json = application/json (default), text = text/plain with an identical body (for platforms that only provide the raw text for signature verification this way, e.g. Make)
  • activebooleanrequired
  • disabledReasonstring | nullrequired
    Reason for automatic deactivation
  • disabledAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • secretHintstringrequired
    First characters of the signing secret
  • createdVia"session" | "api_key" | "oauth"required
  • consecutiveFailuresintegerrequired
    -9007199254740991–9007199254740991
  • failingSincestring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastDeliveryAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastDeliveryStatus"succeeded" | "failed" | nullrequired
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)
  • secretstringrequired
    Signing secret (whsec_…) – only in this response

Possible errors: 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
}'
Response 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"
}

Retrieve webhook endpoint

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

Permission: webhooks:read

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · WebhookEndpoint

  • idstringrequired
  • object"webhook_endpoint"required
  • urlstringrequired
  • descriptionstringrequired
  • eventsArray<enum | "*">required
    Event type or "*" for all
  • payloadFormat"json" | "text"required
    Content-Type of the delivery: json = application/json (default), text = text/plain with an identical body (for platforms that only provide the raw text for signature verification this way, e.g. Make)
  • activebooleanrequired
  • disabledReasonstring | nullrequired
    Reason for automatic deactivation
  • disabledAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • secretHintstringrequired
    First characters of the signing secret
  • createdVia"session" | "api_key" | "oauth"required
  • consecutiveFailuresintegerrequired
    -9007199254740991–9007199254740991
  • failingSincestring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastDeliveryAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastDeliveryStatus"succeeded" | "failed" | nullrequired
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/webhook-endpoints/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"
Response 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"
}

Update webhook endpoint

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

active: true reactivates an automatically deactivated endpoint and resets the failure counter. An endpoint's target URL can only be changed with all the read permissions it was created with (otherwise 403 insufficient_scope).

Permission: webhooks:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Body (JSON) · WebhookEndpointUpdate

  • urlstring (uri)
    HTTPS address that accepts POST requests
    max. 2048 characters
  • eventsArray<enum | "*">
    Event type or "*" for all
  • descriptionstring
    max. 200 characters
  • payloadFormat"json" | "text"
  • activeboolean
    true reactivates (resets the failure counter)

Response 200 · WebhookEndpoint

  • idstringrequired
  • object"webhook_endpoint"required
  • urlstringrequired
  • descriptionstringrequired
  • eventsArray<enum | "*">required
    Event type or "*" for all
  • payloadFormat"json" | "text"required
    Content-Type of the delivery: json = application/json (default), text = text/plain with an identical body (for platforms that only provide the raw text for signature verification this way, e.g. Make)
  • activebooleanrequired
  • disabledReasonstring | nullrequired
    Reason for automatic deactivation
  • disabledAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • secretHintstringrequired
    First characters of the signing secret
  • createdVia"session" | "api_key" | "oauth"required
  • consecutiveFailuresintegerrequired
    -9007199254740991–9007199254740991
  • failingSincestring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastDeliveryAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastDeliveryStatus"succeeded" | "failed" | nullrequired
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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
}'
Response 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"
}

Delete webhook endpoint

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

Also deletes the endpoint's delivery log.

Permission: webhooks:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 204

Success, no content

Possible errors: 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"

Rotate signing secret

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

The old secret becomes invalid immediately. The new one is only included in this response. Only with all the read permissions the endpoint was created with (otherwise 403 insufficient_scope).

Permission: webhooks:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · WebhookEndpointCreated

  • idstringrequired
  • object"webhook_endpoint"required
  • urlstringrequired
  • descriptionstringrequired
  • eventsArray<enum | "*">required
    Event type or "*" for all
  • payloadFormat"json" | "text"required
    Content-Type of the delivery: json = application/json (default), text = text/plain with an identical body (for platforms that only provide the raw text for signature verification this way, e.g. Make)
  • activebooleanrequired
  • disabledReasonstring | nullrequired
    Reason for automatic deactivation
  • disabledAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • secretHintstringrequired
    First characters of the signing secret
  • createdVia"session" | "api_key" | "oauth"required
  • consecutiveFailuresintegerrequired
    -9007199254740991–9007199254740991
  • failingSincestring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastDeliveryAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastDeliveryStatus"succeeded" | "failed" | nullrequired
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)
  • updatedAtstring (date-time)required
    Timestamp (ISO 8601)
  • secretstringrequired
    Signing secret (whsec_…) – only in this response

Possible errors: 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"
Response 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"
}

Send test event

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

Immediately sends a signed webhook.test event to this endpoint and returns the result. No retries; does not count towards automatic deactivation.

Permission: webhooks:write

Path parameters

  • idstringrequired
    Resource ID
    max. 128 characters

Response 200 · WebhookDelivery

  • idstringrequired
  • object"webhook_delivery"required
  • endpointIdstringrequired
  • eventIdstringrequired
  • eventTypeenumrequired
    Values: 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, payment.refunded, payment.reversed, 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"required
  • testbooleanrequired
  • attemptsintegerrequired
    -9007199254740991–9007199254740991
  • nextAttemptAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • lastAttemptAtstring (date-time) | nullrequired
    Timestamp (ISO 8601)
  • responseStatusinteger | nullrequired
    -9007199254740991–9007199254740991
  • responseBodystring | nullrequired
    Start of the response (max. 200 characters; values of sensitive headers and tokens removed)
  • errorstring | nullrequired
  • durationMsinteger | nullrequired
    -9007199254740991–9007199254740991
  • attemptLogArray<object>required
    Recent attempts
    • atstring (date-time)required
      Timestamp (ISO 8601)
    • responseStatusinteger | nullrequired
      -9007199254740991–9007199254740991
    • errorstring | nullrequired
    • durationMsintegerrequired
      -9007199254740991–9007199254740991
  • createdAtstring (date-time)required
    Timestamp (ISO 8601)

Possible errors: 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"
Response 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"
}