Receivables webhooks

Receivables webhooks notify your system when something happens on an assignment — a payment is booked, a credit note is issued, a reminder goes out, or the case moves to a new collection stage. Instead of polling the Receivables API for changes, you receive an HTTP POST shortly after each event, so your integration always has the current state of each assignment.

Setting up a subscription

Receivables webhook subscriptions are set up by Maventa. To enable them, contact Maventa and provide:

Once the subscription is active, your endpoint starts receiving events for the assignments linked to your account. No further setup is required on your side beyond handling the incoming requests.

Events you can receive

A webhook is sent whenever one of the following events occurs on an assignment. Each event carries an event_type you can switch on, plus a data object with the details for that event.

Payload

Every webhook is delivered as an HTTP POST with a JSON body in the following shape:

{
  "delivery_id": "<uuid>",
  "created_at": "<ISO8601-timestamp>",
  "event_data": {
    "assignment_event_id": "<uuid>",
    "assignment_id": "<uuid>",
    "event_type": "<event_type>",
    "party_id": "<uuid>",
    "happened_at": "<ISO8601-timestamp>",
    "data": { }
  }
}

Event data fields

The data object varies by event_type:

Example

A payload for a paid event:

{
  "delivery_id": "b0f4a5c8-1d2e-4f3a-9b6c-2e7d8f9a0b1c",
  "created_at": "2026-07-20T09:15:03+02:00",
  "event_data": {
    "assignment_event_id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
    "assignment_id": "53a4e05d-42f0-4e76-acd6-1a2b3c4d5e6f",
    "event_type": "paid",
    "party_id": "9c8b7a6d-5e4f-3a2b-1c0d-e9f8a7b6c5d4",
    "happened_at": "2026-07-20T09:14:58+02:00",
    "data": {
      "sum_paid": 200.50,
      "booked_at": "2026-07-20",
      "archive_number": "12345"
    }
  }
}

Authentication

To confirm that requests to your endpoint come from Maventa, choose one of the following authentication methods when setting up your subscription. Maventa applies it to every request.

Delivery and retries

A delivery is considered successful when your endpoint responds with any 2xx status code. Any other response, or a timeout, is treated as a failure and retried.

• Timing. Deliveries are dispatched by a background job that runs on a schedule, so expect an event to arrive within a few minutes of it occurring rather than instantly.
• Respond quickly. Keep your handler lightweight — acknowledge the request and do any heavy processing in the background. Requests that take too long are treated as failures.
• Retries. Failed deliveries are retried automatically, up to 10 attempts, before Maventa gives up on that delivery.
• Deduplicate. Delivery is at-least-once, so the same event may arrive more than once. Use delivery_id to recognise and ignore duplicates.
• Ordering. Deliveries for a single assignment are sent in the order the events occurred.