/v2/webhooks/
or use the developer portal described below.
For receiver setup, signature verification, retries, and troubleshooting, use
Webhooks. For a complete API example, follow
Consume Case webhooks.
A company holds at most 20 endpoints, enabled or disabled; the cap is
enforced atomically, so concurrent creates never exceed it and the 21st is
409 webhook_limit_reached. POST /v2/webhook-deliveries/{id}/redeliver/
accepts settled deliveries only (success or failed); a pending,
retrying, or delivering delivery answers 409 delivery_in_progress.
rotate-secret and redeliver take no request body (400 unexpected_body),
and the expensive:webhook-delivery budget is charged only when a redeliver
is accepted with 202. A Partner key acting with X-On-Behalf-Of-Company
cannot manage company endpoints: writes on /v2/webhooks/ and redeliver
answer 403 use_partner_webhooks before any If-Match or query-parameter
check.
The 18 event types below and the six
Mahnservice events
form the 24-event company subscription catalog. Use the exact event keys in
events; the same keys arrive in the payload’s type. Partner integrations
use Partner-owned subscriptions
to receive these events for connected companies.
The Case OpenAPI schema publishes the event envelope as CaseWebhookEvent,
a discriminated union on type. Each event type maps to one payload family;
its data contains the keys listed below, with optional keys marked explicitly.
Dispatch on type, then read data using that family’s model. The objects
are open: new data members and new event types can arrive within /v2/, so
ignore members you do not know and acknowledge, then skip, unknown types (see
Versioning).
Order management
Order lifecycle events useOrderWebhookEvent, with company_id, order_id,
order_url, and claim_ids in data. order.accepted uses
OrderAcceptedWebhookEvent, which adds mandate_id and mandate_url — the
case the order’s claims were accepted into — so a consumer can fetch the
mandate without reading the order first. order.message.created uses
OrderMessageWebhookEvent and adds message_id to the order keys; it is not a
lifecycle event and does not include claim_ids.
Every newly emitted
order.submitted, order.accepted, order.rejected,
order.withdrawn, and order.expired event contains the exact sorted, unique
claim UUID snapshot captured with that transition, including [] when the
order has no claims. These abbreviated payload examples show the lifecycle
data boundary:
The accepted example deliberately has a different order from the submitted
example: review may move a stored claim before acceptance. Reconcile using the
claim UUID from
claim_ids, then refetch /v2/claims/{claim_id}/ to obtain its
current order_id, status, and mandate_id. There is no
claim.order_changed event.
Retained event and delivery envelopes materialized before this contract may
omit claim_ids. Omission means the historical snapshot is unavailable; it
does not mean an empty claim set. Do not synthesize []. Current emissions,
retries, feeds, and redeliveries use the immutable snapshot stored with the
event.
Cases
These events concern accepted collection cases (mandates), their balances, messages, and client requests. Client requests can also belong to an order or CSV upload; their payload uses one of the three contexts below.
For an order request, combine
data.order_id and data.request_to_client_id
to read /v2/orders/{order_id}/requests-to-client/{id}/ and submit its
/answer/ command. The mandate routes apply only when the event carries
mandate_id. See Messages and client requests.
Statements
Statement events announce publication and cancellation of accounting statements. They are separate from Mahnservice invoice events.Document processing
Document-processing events have been retired with URL-based ingestion. They are not selectable and no new document-processing events are delivered or added to the event feed, including for wildcard subscriptions. Followstatus and updated_at through the document’s parent-scoped list or detail
endpoint instead; see Manage documents.
Scanning remains asynchronous.
Configure a subscription in the portal
In the German developer portal, expand Neuen Endpoint hinzufügen to enter the callback URL, the maximum consecutive failures before deactivation, and an optional description. Select events by their exact keys; each has a German explanation. The sections are Mahnservice (Mahnservice API), Auftragsverwaltung, Inkassofälle, and Abrechnungen. Each section has Alle auswählen / Alle abwählen. It changes only that section; selections in other sections remain intact. Selecting every current event in a section stores those explicit keys, not the API wildcard"*".
Collapsing and reopening the create form preserves the draft.
Production and sandbox are separate environments selected by host and
credential. There is no Test/Production selector on a current subscription.
Create and test sandbox subscriptions in the sandbox; see
Authentication and environments.