About webhooks

Overview

Webhooks allow your application to subscribe to specific events or changes on the Akkuro Lending platform in real time. When an event occurs, your server is automatically notified and receives the event data.

Instead of polling the API for updates, webhooks let your application receive real-time notifications as soon as events occur. This approach reduces resource usage, minimizes unnecessary traffic, and helps your system scale efficiently.

Webhooks events

You can register webhook endpoints through the API. All available event APIs can be found on the API schemas. Do as follows to locate them:

1. Go to the API Schemas. Select Lending.

2. Select a functional group and locate an API with “events” in its name. Note that not all functional groups include event APIs.

   Alternatively, you can search for the keyword “events” in the search bar. All available event APIs will appear.

Events are organized by functional group, and some groups have their own set of related event APIs. Here are a few examples of event APIs:

• Process orchestration events API: Triggered by activities related to process orchestration.
• Financing execution events API: Triggered by activities related to financing execution.
• Counterparty management events API: Triggered by activities related to counterparty management.

Event APIs are versioned in the same way as other APIs. Refer to API Versioning.

Webhook payloads

Akkuro Lending delivers HTTP POST payloads along with metadata to your registered webhook endpoint.

The latest versions of webhooks use thin payloads by default. Thin payloads include only the essential identifying information; for example, only a reference ID is included. Reducing payload size improves performance and scalability, and reduces the risk of breaking changes.

If you need the full resource details, use the reference ID to call the corresponding API endpoint and retrieve the relevant data.

Example of a thin payload:

{
  "meta": {
    "id": "18948cb5-68ff-418d-ace8-493e87767bcd",
    "eventName": "process.status-changed",
    "eventEndpointUri": "https://api.example.com/process-orchestration/events/process.status-changed/endpoints/18948cb5-68ff-418d-ace8-493e87767bcd",
    "occurredOn": "2019-07-30T06:43:40.252Z",
    "sentOn": "2019-08-24T14:15:22Z",
    "environment": "Acceptance",
    "brokerKey": "YOURBANK",
    "labelReferenceId": "YOURLABEL"
  },
  "payload": {
    "processReferenceId": "string",
    "filingDateTime": "2019-07-30T06:43:40.252Z"
  }
}

The meta contains the following fields:

• id: A unique identifier for the endpoint registration.
• eventName: The unique name of the event type.
• eventEndpointUri: The API request URL corresponds to an endpoint registration and an associated event.
• occurredOn: Timestamp indicating when the event occurred.
• sentOn: Timestamp indicating when the event was sent to your endpoint. This value may differ from occurredOn due to retries, network latency, or other delivery delays.
• environment: Indicates the current environment, such as production or user acceptance testing (UAT).
• brokerKey: The tenant name.
• labelReferenceId: The white-label reference ID associated with the tenant.

In contrast, there are some older webhook events that may still use full payloads, which contain the entire object data in the event body.

Webhooks security

Since your publicly accessible HTTP endpoints are designed to receive data from external systems, they can be targeted by malicious or fake requests. To protect your endpoint, use a secret token to validate the authenticity of each incoming event, ensuring that your application only processes events sent from Akkuro Lending.

When you register an endpoint for an event, Akkuro Lending returns a unique token. This token is included in the X-Event-Token header of every event request and helps verify if the event request originates from the Akkuro Lending platform, not from an unauthorized source.

Retry mechanism

Learn about the retry mechanism in case of delivery failures.

Successful responses

When your application receives a webhook request, it must return a 2xx HTTP status code to confirm successful delivery. This tells Akkuro Lending that the request was received and processed correctly.

Additionally, your application must return the response within 2 seconds. This ensures your system responds promptly and continues operating efficiently.

Retry logic

The webhook delivery is considered a failure if the returned status code is anything other than 2xx (for example, 4xx or 5xx) or if the response takes longer than 2 seconds.

To handle failures, webhook systems include a built-in retry mechanism. The retry mechanism attempts to resend a webhook request that failed to deliver. The retries are implemented using exponential backoff. Exponential backoff is a retry strategy where the delay between attempts increases after each failure.

There are a total of 12 attempts for retries, including the first attempt to send a webhook request. The following table shows the delay before each attempt and the cumulative elapsed time:

Attempt Number	Delay	Cumulative Delay
1	0 seconds	0 seconds
2	5 seconds	5 seconds
3	10 seconds	15 seconds
4	30 seconds	45 seconds
5	1 minute 30 seconds	2 minutes 15 seconds
6	5 minutes	7 minutes 15 seconds
7	15 minutes	22 minutes 15 seconds
8	30 minutes	52 minutes 15 seconds
9	2 hours	2 hours 52 minutes
10	6 hours	8 hours 52 minutes
11	16 hours	24 hours 52 minutes
12	50 hours	74 hours 52 minutes

Note

Durations for attempts 9 to 12 are rounded down to the nearest minute for simplicity.

After the 12th attempt, if your application still does not return a 2xx status code (which is after 74 hours 52 minutes), the retry mechanism stops and returns a failed status.

Next steps

• Learn how to register webhook endpoints and manage them. See Use webhooks.