# Status Notifications (events) Receive real-time status events from Ropo One into your system. Use this when you need push-based updates. Use [Status Updates](/guides/general-add-ons/status-updates-polling.md) when you prefer polling. * note that polling service doesn't include as wide variety of different actions as status notification service does Please note: * Ropo may add new fields to the messages described in this document without \ separately announcing them. * Changes which affects to current field content or naming or any other thing that breaks \ backward compatibility are announced as an own change process and are not \ implemented in production until users have had enough time to react. ### What you receive Ropo One sends HTTP `POST` requests to your endpoint. Each request contains one event batch. One batch can include multiple message types. One batch contains max **500** messages. ### Setup checklist {% stepper %} {% step %} ### Expose a webhook endpoint Accept `POST` requests over HTTPS. Parse JSON. Make the handler idempotent. Use `id` to dedupe. {% endstep %} {% step %} ### Choose authentication Pick either OAuth2 client credentials or Basic Auth. Share the needed details with Ropo. {% endstep %} {% step %} ### Return the right HTTP status codes Return `2xx` when you have stored the events. Return `4xx` for permanent validation errors. Return `5xx` for transient errors. {% endstep %} {% endstepper %} ### Authentication {% tabs %} {% tab title="OAuth2 (client\_secret\_post)" %} Ropo fetches an access token from **your** token endpoint. Ropo then uses it as a Bearer token for webhook delivery. Share these values with Ropo: * Token URL * Client ID * Client secret * Webhook service endpoint (your receiver URL) * Scope (if your token endpoint requires it) Token request (from Ropo to you): ```http POST Content-Type: application/x-www-form-urlencoded grant_type=client_credentials&scope=&client_id=&client_secret= ``` Expected token response (from you to Ropo): ```json { "token_type": "Bearer", "access_token": "", "expires_in": 3600 } ``` {% endtab %} {% tab title="Basic Auth" %} Ropo uses HTTP Basic Auth for webhook delivery. Share these values with Ropo: * User ID * Password * Webhook service endpoint (your receiver URL) {% endtab %} {% endtabs %} ### Envelope format Every webhook payload uses the same envelope: * `created_at` (string): message creation time in ISO-8601 format. * `id` (string): unique message/batch id. * `data` (object): one or more arrays by message type. `data` can contain any combination of these arrays: * `delivery` * `lcstatus` * `payment` * `contract` * `creditnote` * `duedateupdate` * `disconnect` * `reconnect` {% hint style="info" %} Ropo may add new fields without separate notice. Ignore unknown fields to stay forward-compatible. {% endhint %} ### Common identification rules Most message types identify the case using **either**: * `invoicenumber` * `documentid` (your additional identifier for the document in addition to invoice number) * `jobid` (Ropo One internal identifier) Some messages all three. Don’t assume `documentid` is always present. `cid` is the Ropo One profile id. It is mandatory in all message types. ### Message types
Sample payloads Examples are trimmed for readability. Expect more fields in production. Single message type (delivery): ```json { "created_at": "2022-05-10T11:36:00+00:00", "id": "a0a348f7-764f-40f8-9fc0-d1b76012ca47", "data": { "delivery": [ { "jobid": 123637, "cid": 987654, "distributionchannel": "b2b", "documentid": "2728282", "invoicenumber": "38938", "status": "received", "statustime": "2022-05-10 11:12:36", "description": "document received with notes.", "notes": [{ "note": "Check postal address." }] } ] } } ``` Batch with multiple message types: ```json { "created_at": "2023-11-03T12:10:28+02:00", "id": "bfe59147-96be-47e0-a288-fe4ff8b70fef", "data": { "delivery": [{ "jobid": 123637, "cid": 987654, "status": "delivered", "statustime": "2022-05-10 12:36:00" }], "lcstatus": [{ "code": 2, "cid": 987654, "jobid": 23231, "time": "2022-05-10 10:27:41" }], "payment": [{ "cid": 987654, "jobid": 423145, "time": "2025-09-26 18:27:41", "amount": 50.0 }] } } ```
#### Delivery status (`data.delivery[]`) Tells you how document delivery progressed. Fields you’ll use most: * `status`: `received` | `rejected` | `delivered` | `error` * `statustime`: when the status changed * `distributionchannel`: `post` | `b2b` | `peppol` | `email` | `b2c` * `description`: extra details * `notes[]`: optional notes (received use case) * `errors[]`: optional errors (rejected/error use cases)
Delivery status values * `received`: document received by Ropo One * `rejected`: rejected on import. Check `description` and `errors[]` * `delivered`: delivered to recipient / next party * `error`: delivery failed. Check `description` and `errors[]`
#### Lifecycle status (`data.lcstatus[]`) Tells you when a case moved to a new lifecycle phase. Fields you’ll use most: * `code`: lifecycle code * `status`: lifecycle text (often English) * `time`: when the status change happened * `paydate`: original due date * `currentpaydate`: current due date * `opencapital`, `interest`, `expenses`: open amounts by type (optional)
Lifecycle status codes Most commonly used status codes: ``` 0 Invoicing 1 Reminder 2 Debt collection 11 Draft 16 Legal collection consideration 17 Post-collection 63 Writ of summons sent to district court 101 Paid 102 Job terminated ``` Full list of possible status codes * This list can grow. Store the numeric `code` and treat `status` as informational. ``` 0 Invoicing 1 Reminder 2 Debt collection 6 Debt rescheduling 11 Draft 12 Query – protesting 14 Protested 15 Bankruptcy threat payment notification 16 Legal collection consideration 17 Post-collection 41 Payment plan 55 International legal collection consideration 61 Query – legal collection 63 Writ of summons sent to district court 65 Waiting transfer to enforcement 67 Query – distraint 68 Waiting – estate inventory deed 71 Error – address details 80 Disputed 81 Under review 85 Ropo Legal handling case 86 Query – client's response 89 Address verification 98 Message 101 Paid 102 Job terminated 103 Credit loss 104 Credit invoice 108 Invoice purchasing – sold 110 Under restructuring proceedings 111 Under bankruptcy proceedings 112 In enforcement 121 In international collection 150 Cut-off warning 200 Query – payment reminder 202 Query – identification information 203 Payment plan not followed 208 Regression 211 Query – draft 214 Query – debt collection 300 Invoice (operating) 301 Document (operating) 401 Waiting – funding 402 Invoicing – funding ```
#### Payment (`data.payment[]`) Tells you about payments received and booked in Ropo One. Key points: * `paydate` is deprecated. * Use `paymentdate`, `accountdate`, and `settlementdate` for booking clarity. * `paymentdate` = Day when payment was made. * `accountdate` = Day when payment was booked to account * `settlementdate` = Day when payment was paid out from Ropo * `openamount` includes capital + client expenses + interest. * `amountbreakdown` and `openamountbreakdown` includes detailed view what receivable types were paid and are still open. #### Contract (`data.contract[]`) Tells you about contract data changes, when contract updates are part of the agreed lifecycle. Key fields: * `contract_no` (mandatory) * `contractstatus` (mandatory, example: `active`) * `termination_date` and `terminationterm` may be present if termination is calculated #### Credit note (`data.creditnote[]`) Tells you when a credit note is: * `allocated` to a debit invoice * `unallocated` (allocation removed) * `refunded` to the end customer Notes: * Allocation/unallocation may reference invoices via bill numbers and/or job IDs. * Credit notes allocated based on allocation info received from the client are **not** reported. #### Due date update (`data.duedateupdate[]`) Sent when due date changes in Ropo One. Important fields: * `currentpaydate`: the new due date * `source`: why/how the update happened * `contract[]`: optional list of contract numbers (can be 1..n)
Due date update source values * `restapi`: updated from an external source via Ropo REST API * `online`: updated by end customer in Ropo online service * `aspa_end_customer_request`: updated by Ropo customer service on end customer request * `aspa_other_reason`: updated by Ropo customer service for other reasons * `einvoice_error`: updated after e-invoice negative ack, then fixed and resent
#### Disconnect / reconnect (`data.disconnect[]`, `data.reconnect[]`) Sent when a process recognizes a disconnect/reconnect action is needed. Both contain: * `usageplacecode` (mandatory) * `contract_no` (mandatory) * `invoices[]` with invoice identifiers (`jobid`, `invoicenumber`, optional `documentid`) Disconnect may include `disconnectiondate`. ### Error response body (optional) You can return a problem details body with non-2xx responses. RFC 7807 is recommended. ```json { "type": "https://example.com/problems/invalid-payload", "title": "Invalid payload", "status": 400, "detail": "Missing required field: data.delivery[0].cid" } ``` ### Webhook definition (OpenAPI) {% openapi-webhook spec="ropo-one" name="Status notification service" method="post" %} [ropo-one](https://rc.ropo24.fi/swagger/swagger.json) {% endopenapi-webhook %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://dev.ropo.com/guides/general-add-ons/status-notifications-events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.