Webhook Callbacks Documentation

get

https://rivage.immo/webhooks/callbacks

Webhook Callbacks Documentation

This page provides detailed documentation about the webhook callbacks sent by the Rivage API.

How Callbacks Work

When an event occurs in your Rivage account (such as creating, updating, or deleting a resource),
and you have configured a webhook to listen for that event, the following process occurs:

The event is detected by our system
If you have a webhook configured for that event type and model, a webhook event is created
A POST request is sent to your webhook URL with a JSON payload
Your server should process the webhook and return a 2xx response

Webhook Payload Format

All webhook payloads follow this structure:

{
  "event_type": "created | updated | deleted",
  "model_name": "ModelName",
  "payload": { /* Model-specific data */ },
  "created_at": "2023-06-15T12:30:45Z"
}

Authentication and Security

Webhooks are sent with the following headers:

Content-Type: application/json
User-Agent: Rivage-Webhook/1.0

To ensure security:

Verify the User-Agent header
Only accept POST requests to your webhook endpoint
Use HTTPS for your webhook URL
Process webhooks idempotently (handle duplicate deliveries gracefully)

Webhook Delivery Guarantees

We implement a "at least once" delivery policy, which means:

You may occasionally receive the same webhook more than once
You should implement idempotent processing
Failed webhook deliveries are retried up to 8 times
Retries use exponential backoff to avoid overwhelming your servers

Event Types

For each model, we support the following event types:

created: When a new resource is created
updated: When an existing resource is modified
deleted: When a resource is deleted

Supported Models

Webhooks are available for the following models:

AccountingAccount
AccountingEntry
AccountingTransaction
Asset
AssetGroup
BankTransaction
BillingLine
BillingRate
GliProviderStatement
Invoice
LeasingContract
ManagementContract
Message
PaymentOrder
Profile
RentRevision
SepaFile
SepaMandate
TransactionConfiguration
Upload

Each model section below provides specific payload examples for each event type.

Business Events

In addition to model-based events, webhooks also support the following business-specific events:

rent.call - Rent Call Created

Triggered when a rent call is created for a leasing contract.
The webhook includes the rent receipt details, accounting entries, and full contract information.

Payload Structure:

{
  "event_name": "rent.call",
  "payload": {
    "event": "rent.call",
    "timestamp": "2025-11-09T12:07:45+01:00",
    "rent_receipt": { /* Rent receipt with table rows and tenant info */ },
    "accounting_event": { /* Accounting event details */ },
    "accounting_event_group": { /* Event group tracking rent call */ },
    "leasing_contract": { /* Full leasing contract data */ }
  },
  "created_at": "2025-11-09T12:52:54+01:00"
}

rent.received - Rent Payment Received

Triggered when a tenant payment is received and processed into the accounting system.
The webhook includes accounting entries showing how the payment was distributed.

Payload Structure:

{
  "event_name": "rent.received",
  "payload": {
    "event": "rent.received",
    "timestamp": "2025-11-09T16:33:37+01:00",
    "accounting_event": {
      "processed_at": "2025-11-09",
      "leasing_contract_id": "lc_52d93c7c294e3465a516a9d3",
      "nature": "rent_received",
      "amount_received_in_cents": 25713,
      "accounting_entries": [ /* Array of accounting entries */ ]
    },
    "accounting_event_group": { /* Event group containing full rent information */ }
  },
  "created_at": "2025-11-09T16:33:43+01:00"
}

rent_receipt.created - Rent Receipt PDF Generated

Triggered when a rent receipt (quittance de loyer) PDF is generated for a tenant.
The webhook includes the receipt details, upload file information, and related accounting data.

Payload Structure:

{
  "event_name": "rent_receipt.created",
  "payload": {
    "event": "rent_receipt.created",
    "timestamp": "2025-11-09T16:35:16+01:00",
    "accounting_event_group": { /* Full accounting event group */ },
    "upload": {
      "id": "u_578aee4e6326ec317f6a087e",
      "nature": "rent_receipts",
      "file_url": "https://..." /* S3 URL to PDF file */
    },
    "leasing_contract": { /* Leasing contract details */ },
    "rent_receipt": {
      "table_rows": [ /* Receipt table rows with amounts and descriptions */ ],
      "tenant_full_name": "Adeltrude Roche",
      "tenant_reference": "LOC-9132643B",
      "tenant_address": { /* Tenant address details */ }
    }
  },
  "created_at": "2025-11-09T16:35:17+01:00"
}

deposit.requested - Deposit Refund Requested

Triggered when a deposit refund is requested at lease termination.
The webhook includes accounting entries and the related lease contract information.

Payload Structure:

{
  "event_name": "deposit.requested",
  "payload": {
    "event": "deposit.requested",
    "timestamp": "2025-11-09T15:32:20+01:00",
    "invoice": {
      "id": "ae_4f13b9264d6c8b0fca452914",
      "nature": "call_refund_deposit",
      "processed_at": "2025-11-09",
      "accounting_entries": [ /* Accounting entries for deposit refund */ ],
      "leasing_contract_id": "lc_6f574b847c939d39cf978336",
      "amount_received_in_cents": null
    },
    "leasing_contract": {
      "status": "move_out",
      "deposit_in_cents": 165871,
      "end_date": "2025-11-04"
      /* Additional contract fields */
    }
  },
  "created_at": "2025-11-09T15:32:22+01:00"
}

management_report.created - Management Report PDF Generated

Triggered when a management report (compte rendu de gestion) is generated for a landlord.
The webhook includes the PDF file information and accounting data for the reporting period.

Payload Structure:

{
  "event_name": "management_report.created",
  "payload": {
    "event": "management_report.created",
    "timestamp": "2025-11-09T15:08:55+01:00",
    "upload": {
      "id": "u_3fe46344c3406ae175a3681a",
      "nature": "management_reports",
      "file_url": "https://..." /* S3 URL to PDF file */
    },
    "accounting_event_group": { /* Full accounting event group */ },
    "management_report": { /* Management report with table rows and amounts */ }
  },
  "created_at": "2025-11-09T15:08:56+01:00"
}

sepa_transfer.sent - SEPA Transfer File Sent

Triggered when a SEPA credit transfer file is marked as sent (validated for bank submission).
The webhook includes the SEPA file details and an array of transfers grouped by batch reference
(matching the SEPA file generation grouping). Each transfer includes the profile, total amount,
remittance information (libellé), counterparty type, and the individual payment orders with
their related assets/leasing contracts.

Payload Structure:

{
  "event_name": "sepa_transfer.sent",
  "payload": {
    "event": "sepa_transfer.sent",
    "timestamp": "2025-11-09T15:08:55+01:00",
    "sepa_file": {
      "id": "sf_3fe46344c3406ae175a3681a",
      "reference": "SEPA-20251109-A1B2C3D4",
      "nature": "credit_transfer",
      "status": "sent",
      "control_sum_in_cents": 125000,
      "created_at": "2025-11-09T14:00:00+01:00",
      "sent_at": "2025-11-09T15:08:55+01:00"
    },
    "transfers": [
      {
        "batch_reference": "SCT-A1B2C3D4",
        "amount_in_cents": 75000,
        "counterparty_type": "landlord",
        "remittance_information": "Ref: SCT-A1B2C3D4 - Lots: LOT-001",
        "due_date": "2025-11-15",
        "profile": {
          "id": "p_4f13b9264d6c8b0fca452914",
          "email": "[email protected]",
          "full_name": "Jean Dupont",
          "reference": "PRO-1234ABCD"
        },
        "payment_orders": [
          {
            "id": "po_578aee4e6326ec317f6a087e",
            "amount_in_cents": 75000,
            "due_date": "2025-11-15",
            "asset": {
              "id": "a_6f574b847c939d39cf978336",
              "reference": "LOT-001",
              "nature": "apartment"
            },
            "asset_group": {
              "id": "ag_7a685c958d040e40d0089447",
              "reference": "IMM-001"
            },
            "leasing_contract": {
              "id": "lc_52d93c7c294e3465a516a9d3",
              "reference": "BAIL-001",
              "status": "active"
            }
          }
        ]
      }
    ]
  },
  "created_at": "2025-11-09T15:08:56+01:00"
}

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Response

200Webhook Callbacks Documentation