Use webhooks

Overview

Learn how to register and manage a webhook endpoint via API to receive Akkuro Lending events.

After you register a webhook endpoint, Akkuro Lending can push real-time event data to your application’s webhook endpoint when events happen. Webhook events are delivered as structured HTTP POST requests.

In this guide, we use the Counterparty Management event API for demonstration purposes. For detailed information on parameters, requests, and responses, refer to the Event APIs in the API Schema.

Register webhook endpoints

This section explains how to register webhook endpoints using the API.

Prerequisites

Before registering a webhook endpoint, you need to:

• Be familiar with locating available event APIs on the API schema site. See Webhooks events.
• Have a publicly accessible URI where your application can receive webhook events.

Retrieve all event types

Use the following endpoint to retrieve all event types that can trigger a webhook:

• Method: GET
• Endpoint: /{functional-group}/events/event-types

Note

In case this endpoint is not available, as a temporary workaround, you can check the example event payload endpoints to identify supported event types.

Request example

The following example shows how to get all event types related to a counterparty.

curl --location --request GET 'https://api.eu.lending.akkuro.io/counterparty-management/events/event-types' \
--header 'Accept: application/json;api-version=2024.1.0' \
--header 'Authorization: Bearer {your_JWT_token}'

Response example

The API returns a list of available event names as below:

[
    "counterparty.merged",
    "counterparty_operational.consolidated",
    "counterparty_master.consolidated"
]

You can understand the meaning of these event types from their names:

• counterparty.merged: Two or more counterparty records have been merged into one.
• counterparty_operational.consolidated: Operational data related to a counterparty has been consolidated.
• counterparty_master.consolidated: Master records for a counterparty have been consolidated.

Register a new endpoint

Register your application's URI to subscribe to available events. When any event occurs, data will be sent to this URI in real-time.

There is no centralized endpoint object for all webhook event types. Each event type must be registered individually through separate API calls.

Make the following request:

• Method: POST
• Endpoint: /{functional-group}/events/{event-name}/endpoints

Path parameters:

Parameter	Type	Description	Required
event-name	String	The unique name of the event type you retrieved in this section.	Yes

Body parameters:

Parameter	Type	Description	Required
uri	String	The publicly accessible URI where your application receives webhook events.	Yes

Request example

The following example shows how to register a new endpoint for the counterparty.merged event.

curl --location --request GET 'https://api.eu.lending.akkuro.io/counterparty-management/events/counterparty.merged/endpoints' \
--header 'Accept: application/json;api-version=2024.1.0' \
--header 'Authorization: Bearer {your_JWT_token}' \
--data '{
  "uri": "https://backend.yourbank.tld/webhooks?event=counterparty.merged"
}'

Response example

When the endpoint is registered successfully, it returns a 201 HTTP status code response:

{
    "id": "689062a7fc423348d145db30",
    "eventName": "counterparty.merged",
    "createdOn": "2025-08-04T07:35:03.4828363Z",
    "token": "aSTYanRlQ9HiCub5TNPVSZ5frY2htZnRShroZp5wJfM=",
    "uri": "https://backend.yourbank.tld/webhooks?event=counterparty.merged"
}

The response includes the following components:

• id: A unique identifier for the endpoint registration. This can be used to manage the webhook endpoints. See Manage webhook.
• eventName: The unique name of the event type.
• createdOn: Timestamp indicating when the endpoint is registered.
• token: A unique token used to secure your endpoint, explained in Secure your webhook endpoint.
• uri: The publicly accessible URI where your application receives webhook events.

Secure your webhook endpoint

After your endpoint is successfully registered, you will receive a unique token in the response. Store this token securely in your server-side environment. Akkuro Lending will include the token in the X-Event-Token header of every HTTP event sent to your server. Your application should check the values to validate if the request is authentic and from Akkuro Lending.

tip

If you forget the token for a registered endpoint, you can retrieve it. Refer to Retrieve a token for a registered endpoint.

Manage webhooks

This section explains how to manage webhook endpoints using the API. You can perform the following actions:

• Retrieve a token for a registered endpoint.
• Retrieve all the endpoints and their details that are currently registered.
• Update your webhook endpoints.
• Delete your webhook endpoints.
• Preview a webhook payload.

Prerequisites

You must have already registered a webhook endpoint. Refer to Register a webhook endpoint.

Retrieve a token for a registered endpoint

Retrieve the token for a specific endpoint registered to an event. This token is used to secure your webhook endpoint.

Make the following request:

• Method: GET
• Endpoint: /{functional-group}/events/{event-name}/token/{id}

Request example

The following example shows how to retrieve a token for a registered endpoint.

curl --location --request GET 'https://api.eu.lending.akkuro.io/counterparty-management/events/counterparty.merged/token/68906d98fc423348d145db33' \
--header 'Accept: application/json;api-version=2024.1.0' \
--header 'Authorization: Bearer {your_JWT_token}'

Response example

A successful response returns a 200 OK status code with the token.

{
  "token": "string"
}

Retrieve all registered webhook endpoints

After registering webhook endpoints, you can view all the endpoints that you have currently registered to receive webhook events, along with their details.

Make the following request:

• Method: GET
• Endpoint: /{functional-group}/events/{event-name}/endpoints

Request example

The following example shows how to get all registered endpoints for the counterparty.merged event.

curl --location --request GET 'https://api.eu.lending.akkuro.io/counterparty-management/events/counterparty.merged/endpoints' \
--header 'Accept: application/json;api-version=2024.1.0' \
--header 'Authorization: Bearer {your_JWT_token}'

Response example

A successful response returns a 200 HTTP status code.

[
    {
        "id": "66822967d03468cebc40c60a",
        "eventName": "counterparty.merged",
        "createdOn": "2024-07-01T03:58:31.427Z",
        "token": "uUhvrPup1En9s1aLkgxtSB/kDDjWmba4TB+g/5w6LQc=",
        "uri": "https://backend.yourbank.tld/webhooks?event=counterparty.merged"
    },
    {
        "id": "66a323957e4155a7e5b1a4be",
        "eventName": "counterparty.merged",
        "createdOn": "2024-07-26T04:18:29.82Z",
        "token": "bCvQKPwmALv9aNRHOh6D71MArgtFBBPUQtXl2uq1v64=",
        "uri": "https://backend.mybank.tld/webhooks?event=counterparty.merged"
    }
]

Update a registered webhook endpoint

Update the URI of a registered endpoint to change where your application receives event data.

Make the following request:

• Method: PUT
• Endpoint: /counterparty-management/events/{event-name}/endpoints/{id}

Request example

The following example shows how to update a registered endpoint.

curl --location --request PUT 'https://api.eu.lending.akkuro.io/counterparty-management/events/counterparty.merged/endpoints/68906d98fc423348d145db33' \
--header 'Accept: application/json;api-version=2024.1.0' \
--header 'Authorization: Bearer {your_JWT_token}' \
--data '{
  "uri": "https://backend.tld/webhooks?event=counterparty.merged"
}'

When you have updated the endpoint successfully, it returns a 204 No Content status code response.

Delete a registered webhook endpoint

Delete a registered webhook endpoint if your application no longer needs to receive event data for that endpoint.

Make the following request:

• Method: DELETE
• Endpoint: /counterparty-management/events/{event-name}/endpoints/{id}

Request example

The following example shows how to remove a webhook endpoint.

curl --location --request DELETE 'https://api.eu.lending.akkuro.io/counterparty-management/events/counterparty.merged/endpoints/68906d98fc423348d145db33' \
--header 'Accept: application/json;api-version=2024.1.0' \
--header 'Authorization: Bearer {your_JWT_token}'

When you have deleted the endpoint successfully, it returns a 204 No Content status code response.

Retrieve event payload examples

Previewing a webhook payload helps developers integrate and test their endpoints. It shows the exact format and fields to expect, so you can handle and parse the data correctly.

Make the following request:

• Method: GET
• Endpoint: /{functional-group}/events/{event-name}/example

Request example

The following example shows how to retrieve a sample payload for the counterparty.merged event.

curl --location --request GET 'https://api.eu.lending.akkuro.io/counterparty-management/events/counterparty.merged/example' \
--header 'Accept: application/json;api-version=2024.1.0' \
--header 'Authorization: Bearer {your_JWT_token}'

To learn how to read your webhook payloads, refer to Webhook payloads.