Skip to main content

Notifications

This section details the asynchronous notifications dispatched by Koncili.

Koncili issues automated notifications via HTTP POST requests to the callback URL previously configured by the integrator. All notification payloads strictly adhere to the following JSON schema:

Important

The notification endpoint must be public to ensure the successful receipt of incoming messages.

{
  "notificationType": "EVENT_TYPE",
  "timestamp": "ISO8601",
  "payload": {
    // Event-specific data
  }
}

Notification Types​

The following list details all notification types dispatched by Koncili. For all events, the expected response is:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "success"}

1. Notification URL Test​

{
  "notificationType": "TEST_NOTIFICATION",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": null
}

2. Account Created​

Dispatched upon new account activation:

{
  "notificationType": "ACCOUNT_CREATED",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "accountId": 1234,
    "status": "ACTIVE"
  }
}

3. Reconciliation Completed​

Dispatched upon the conclusion of a reconciliation process:

Information

There are two possible notification scenarios: reconciliation completed successfully or with errors.

{
  "notificationType": "RECONCILIATION_COMPLETED",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "accountId": 1234,
    "reconciliationId": 4321,
    "resolvedEndDate": "2025-06-13T16:00:00Z",
    "situation": "CONCILIED"
  }
}
{
  "notificationType": "RECONCILIATION_COMPLETED",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "accountId": 1234,
    "reconciliationId": 4321,
    "resolvedEndDate": null,
    "situation": "ERROR"
  }
}

4. Temporary Rate Limiting​

Dispatched when the API is temporarily blocked due to rate limiting or security protocols:

{
  "notificationType": "BLOCKED_TEMPORARY",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "integratorName": "INTEGRATOR NAME",
    "durationMinutes": 60
  }
}

5. Permanent Block​

Dispatched following repeated attempts after a temporary block has been issued:

{
  "notificationType": "BLOCKED_PERMANENT",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "integratorName": "INTEGRATOR NAME"
  }
}

6. Access Restored​

Notification triggered upon access restoration:

{
  "notificationType": "UNLOCKED",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "integratorName": "INTEGRATOR NAME"
  }
}