Digital lending
Hook notifications

Register for hooks

17min

Base Address

Registrations can also be created, updated, and restarted via the Cos.Lending.Hooks UI:



POST /Hooks/v2/Registrations

Use this call to:

  • Create a registration to webhook events
  • Edit a webhook registration
  • Restart a registration if it is suspended

Request URL https:// .../Hooks/v2/Registrations

Sample request in cURL - POST /Hooks/v2/Registrations

In the request below, hookName shows the event registered as LoanStatusUpdated.

Curl


Duplication Registrations

The default behavior for hooks registration, is to either create or update the registration based on the MPLID and the hookName, assuming there is only one registration per combination of Mplid/hookName. In certain use cases, you might want to create two registrations for the same event. For example, one web hook, and one email hook. To do this, you need to supply a new Guid for the Id field of the registration.

Webhook attributes

Attribute

Description

Id

string

This field can be null or populated with the registration GUID for the registration.

null - when creating a new registration

GUID - when updating or unsuspending an existing registration

applicationName

string

Should always be Cos.Lending

hookName

string

The name of the hook you want to register for:

- LoanStatusUpdated

- ComplianceLoanFailed

- RailUpdated

hookCorrelationId

string

3-letter MPL ID

suspended

boolean

True or false.

True if the registration should be suspended and not send webhooks. False if the registration should be active.

If you edit a suspended registration, false will restart the registration.

options

object

Select the relevant values for the fields below.

options.hookType

Delivery method for the event (enum).

Select from:

- Web (for webhooks)

- Email

- Slack

- Message (coming soon)

- RabbitMq (coming soon)

- Sqs (coming soon)

options.httpMethod

string

POST

options.uri

string

The URL to receive webhook events/

options.headers

string array

Key/Value pairs of Headers and values. Each header can have an array of values:

"Headers": {

"FirstHeader": [

"test1",

"test2"

],

"secondHeader":["single value"]

}

options.authenticationOptions

object

Authentication options for web hooks.

Select from:

- None

- Basic

- oidc

Sample response in JSON - POST /Hooks/v2/Registrations

Use the id received in the response to update or restart the registration.

JSON


Webhooks without Authentication

JSON


Webhooks with Basic Authentication

JSON


Webhooks with OIDC Authentication

OpenID Connect using your own authentication authority.

OIDC setup must be implemented first

Your OIDC must be fully implemented in order to use Hooks notifications with OIDC authentication. This includes setting up a discovery endpoint /.well-known/openid-configuration

JSON


Slack hook registration

Hook events can also be sent to your slack channels. To do this you must:

  1. Create a slack bot with permissions to write to a channel in your workspace.
  2. Retrieve the auth token of the slackbot.
  3. Add the slackbot to the slack channel that you wish to register.
  4. Register the channel to receive events on the Cos.Lending.Hooks UI, or via the API payload below.

IMPORTANT Registering to a slack channel is not recommended if automation is needed. For complete automation, it is recommended to use "web" hooks instead.



JSON


Email hook registration

Hook events can also be sent to your Email address, or group email address.

  1. Register the channel to receive events on the Cos.Lending.Hooks UI, or via the API payload below.

IMPORTANT Registering to receive events via email is not recommended if automation is needed. For complete automation, it is recommended to use "web" hooks instead.



JSON




Testing webhook registration

To test registering webhooks, configure a URL for the specific event you are registering to. If a URL is not yet available, then you can use the webhook.site as a temporary test solution. Follow these instructions to test the webhooks.

To register your URL to receive webhook events:

  1. Click New on the top menu. The site returns Your unique URL.
  2. Copy to clipboard your unique URL.

If you already have other webhooks registered, the browser might automatically direct you to the URL you've used.

Document image




4. Paste the copied URL into the options.uri field of the JSON body.

5. Send the Registration API call with hook type "web" to register for webhooks.

The response field Result.id is the RegistrationId of the event. You can find the registration ID with the call GET Hooks/v2/Registrations.

Repeat the process for each event that you want to register for.

🤔
Have a question?
Our super-smart AI, knowledgeable support team and an awesome community will get you an answer in a flash.
To ask a question or participate in discussions, you'll need to authenticate first.