Lending
Hook notifications

27min
Overview
Hooks is a notification system, used by Arix, to update you on the status of your loan. Hooks report to your system with real-time notifications when an event happens on Arix. You have to register to receive hooks for each relevant event type by configuring the destination and delivery method, most commonly webhooks. When that event occurs, a Hook is triggered and reports the updates to your system via the chosen delivery method.
For example, if a rail status changes to returned, a RailUpdated hook event would be triggered, and reported to the partner notifying them of the event. This notification will only be sent out, if you have previously registered to receive this type of event (RailUpdated), and the registration is active.
IMPORTANT
To access the links below you must have the following IP addresses allowlisted:
Sandbox - 66.206.202.39 , 66.206.202.12
Production -66.206.202.62 , 66.206.202.15
Swagger: https://lendingsandbox.crbcos.com/hooks/swagger/index.html﻿
Base URL for sandbox: https://lendingsandbox.crbcos.com/﻿
Sandbox UI: https://lendingappsandbox.crbcos.com/hooks/registrations﻿
Production UI: https://lendingapp.crbcos.com/hooks/registrations﻿
API Scope:
CosLending:Hooks:stg for sandbox
CosLending:Hooks:prd for production
By default, a webhook that fails will retry 3 times with a delay interval of 5 minutes. Different Intervals can be configured for a registration by the CR support team.
Events can also be resent manually via the hooks UI, although there is a retention policy of 60 days for events in the system. 
Sample Events
LoanStatusUpdate
This event is reported every time the status of a loan is changed.
JSON
{
    "Id": 0,
    "LoanId": "3f07773b-5ba5-43e6-bf30-aea200361dad",
    "Status": 104,
    "TimeStamp": "2022-05-30T03:17:43.6233616+00:00",
    "DateInserted": "0001-01-01T00:00:00+00:00"
}
{
    "Id": 0,
    "LoanId": "3f07773b-5ba5-43e6-bf30-aea200361dad",
    "Status": 104,
    "TimeStamp": "2022-05-30T03:17:43.6233616+00:00",
    "DateInserted": "0001-01-01T00:00:00+00:00"
}
﻿
ComplianceLoanFailed
This event is reported every time the loan fails to pass all compliance checks.
JSON
{
     "MPLId": "xxx",
     "LoanId": "...guid...",
     "CreateDate": "date",
     "FailedRulesReasons": [
        {
           "RuleName": "rule name",
           "Rule": "some string",
           "Data": "some string",
           "Result": true,
           "FailedComplianceID": 67
        }
     ]
  }
{
     "MPLId": "xxx",
     "LoanId": "...guid...",
     "CreateDate": "date",
     "FailedRulesReasons": [
        {
           "RuleName": "rule name",
           "Rule": "some string",
           "Data": "some string",
           "Result": true,
           "FailedComplianceID": 67
        }
     ]
  }
﻿
RailUpdated
This event is reported when there is a status update to a rail that was requested
JSON
{ 
      "Id":0,
      "RailId":"…ID of rail that is received when rail created…",
      "LoanId":"fd331267-6ac2-4818-9d0f-ab2f00747b61",
      "RailType":8,
      "AmountFunded":8500.0,
      "RailTransactionId":"…railid from cos…",
      "FundResult": int(this is enum RailResultType), 
      "Message":"Description of rail created if no error returned",
      "ProcessedAt":"2019-12-26T07:05:09Z",
      "TransactionGroupId":"9dde776d-0c04-4bc8-9c9c-e0ad9a83c447"
   }
{ 
      "Id":0,
      "RailId":"…ID of rail that is received when rail created…",
      "LoanId":"fd331267-6ac2-4818-9d0f-ab2f00747b61",
      "RailType":8,
      "AmountFunded":8500.0,
      "RailTransactionId":"…railid from cos…",
      "FundResult": int(this is enum RailResultType), 
      "Message":"Description of rail created if no error returned",
      "ProcessedAt":"2019-12-26T07:05:09Z",
      "TransactionGroupId":"9dde776d-0c04-4bc8-9c9c-e0ad9a83c447"
   }
﻿
POST /Hooks/v2/Registrations
Use this call to:
Create a registration to hook events
Edit a hook registration
Restart a registration if it is suspended
Request URL https:// .../Hooks/v2/Registrations
Editing a Registration
To edit an existing registration, use the same API endpoint as for creating a registration.
How It Works
Include the ID of the registration in the POST request to modify an existing entry.
The API automatically determines whether to create or update a registration based on:
MPLID 
hookName
If a registration already exists for the given MPLID/hookName combination, the API will update it instead of creating a new one.
If no matching registration is found, a new one will be created.
When editing a registration via the UI, any stored passwords or tokens will be shown hashed on the UI. For security reasons, You will need to re-enter these credentials when modifying the registration. 
﻿
Sample request in cURL - POST /Hooks/v2/Registrations
In the request below, hookName shows the event registered as LoanStatusUpdated.
Curl
curl --location --request POST 'https://lendingsandbox.crbcos.com/Hooks/v2/Registrations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Token>' \
--data-raw '{
  "id": null,
  "applicationName": "Cos.Lending",
  "hookName": "LoanStatusUpdated",
  "hookCorrelationId": "Your 3 letter MPL ID",
  "options": {
    "hookType": "Web",
    "httpMethod": "POST",
    "uri": "Add your URL here, that is specific to this event type",
    "headers": {
      "headerName": [
        "LoanStatusUpdated"
      ]
    },
    "authenticationOptions": {
      "authenticationType": "None"
    }
  }, 
  "suspended": false
}'
curl --location --request POST 'https://lendingsandbox.crbcos.com/Hooks/v2/Registrations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Token>' \
--data-raw '{
  "id": null,
  "applicationName": "Cos.Lending",
  "hookName": "LoanStatusUpdated",
  "hookCorrelationId": "Your 3 letter MPL ID",
  "options": {
    "hookType": "Web",
    "httpMethod": "POST",
    "uri": "Add your URL here, that is specific to this event type",
    "headers": {
      "headerName": [
        "LoanStatusUpdated"
      ]
    },
    "authenticationOptions": {
      "authenticationType": "None"
    }
  }, 
  "suspended": false
}'
﻿
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
{
    "Version": "2.0",
    "IsSuccessful": true,
    "StatusCode": 200,
    "Result": {
        "id": "eb62ffbd-7ed4-4146-be48-7f2a46551c0e",
        "applicationName": "cos.lending",
        "hookName": "LoanStatusUpdated",
          ...
        ...
        ..
    }
}
{
    "Version": "2.0",
    "IsSuccessful": true,
    "StatusCode": 200,
    "Result": {
        "id": "eb62ffbd-7ed4-4146-be48-7f2a46551c0e",
        "applicationName": "cos.lending",
        "hookName": "LoanStatusUpdated",
          ...
        ...
        ..
    }
}
﻿
Webhooks without Authentication
JSON
"options": {
    "hookType": "Web",
    "httpMethod": "POST",
    "uri": "Add your URL here, that is specific to this event type",
    "headers": {
      "headerName": [
        "Any Header you want to add to all events"
      ]
    },
    "authenticationOptions": {
      "authenticationType": "None"
    }
  }
"options": {
    "hookType": "Web",
    "httpMethod": "POST",
    "uri": "Add your URL here, that is specific to this event type",
    "headers": {
      "headerName": [
        "Any Header you want to add to all events"
      ]
    },
    "authenticationOptions": {
      "authenticationType": "None"
    }
  }
﻿
Webhooks with Basic Authentication
JSON
"options": {
    "hookType": "Web",
    "httpMethod": "POST",
    "uri": "Add your URL here, that is specific to this event type",
    "headers": {
      "headerName": [
        "Any Header you want to add to all events"
      ]
    },
    "authenticationOptions": {
      "authenticationType": "Basic",
      "username": "yyy",
      "password": "1234"
    }
  }
"options": {
    "hookType": "Web",
    "httpMethod": "POST",
    "uri": "Add your URL here, that is specific to this event type",
    "headers": {
      "headerName": [
        "Any Header you want to add to all events"
      ]
    },
    "authenticationOptions": {
      "authenticationType": "Basic",
      "username": "yyy",
      "password": "1234"
    }
  }
﻿
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
"options": {
    "hookType": "Web",
    "httpMethod": "POST",
    "uri": "Add your URL here, that is specific to this event type",
    "headers": {
      "headerName": [
        "headerValue"
      ]
    },
    "authenticationOptions": {
        "authenticationType": "Oidc",
        "authorityUrl": "",
        "clientId": "",
        "clientSecret": "",
        "scope": ""
    }
  }
"options": {
    "hookType": "Web",
    "httpMethod": "POST",
    "uri": "Add your URL here, that is specific to this event type",
    "headers": {
      "headerName": [
        "headerValue"
      ]
    },
    "authenticationOptions": {
        "authenticationType": "Oidc",
        "authorityUrl": "",
        "clientId": "",
        "clientSecret": "",
        "scope": ""
    }
  }
﻿
Slack hook registration
Hook events can also be sent to your slack channels. To do this you must:
Create a slack bot with permissions to write to a channel in your workspace.
Retrieve the auth token of the slackbot.
Add the slackbot to the slack channel that you wish to register.
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
{
  "id": null,
  "applicationName": "Cos.Lending",
  "hookName": "LoanNoteAdded",
  "hookCorrelationId": "Your 3 letter MPL ID",
   "options": {
    "hookType": "Slack",
    "authToken": "Your Slack API bot token.",
    "channel": "The channel name. You must also add your slack bot to this channel"
    },
  "suspended": false
}
{
  "id": null,
  "applicationName": "Cos.Lending",
  "hookName": "LoanNoteAdded",
  "hookCorrelationId": "Your 3 letter MPL ID",
   "options": {
    "hookType": "Slack",
    "authToken": "Your Slack API bot token.",
    "channel": "The channel name. You must also add your slack bot to this channel"
    },
  "suspended": false
}
﻿
Email hook registration
Hook events can also be sent to your Email address, or group email address. 
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
{
  "id": null,
  "applicationName": "Cos.Lending",
  "hookName": "LoanNoteAdded",
  "hookCorrelationId": "Your 3 letter MPL ID",
    "options": {
                    "hookType": "Email",
                    "to": [
                        "email address"
                    ],
                    "cc": [
                        null
                    ],
                    "bcc": [
                        null
                    ]
                },
  "suspended": false
}
{
  "id": null,
  "applicationName": "Cos.Lending",
  "hookName": "LoanNoteAdded",
  "hookCorrelationId": "Your 3 letter MPL ID",
    "options": {
                    "hookType": "Email",
                    "to": [
                        "email address"
                    ],
                    "cc": [
                        null
                    ],
                    "bcc": [
                        null
                    ]
                },
  "suspended": false
}
﻿
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:
Go to https://webhook.site/﻿
Click New on the top menu. The site returns Your unique URL.
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.
﻿
﻿
    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.
DELETE /Hooks/v2/Registrations
Request URL https:// .../Hooks/v2/Registrations
Use this call to unregister any hook event you are registered to.
Sample request in cURL - DEL /Hooks/v2/Registrations
Curl
curl --location --request DELETE 'https://lendingsandbox.crbcos.com/Hooks/v2/Registrations?id=eb62ffbd-7ed4-4146-be48-7f2a46551c0e' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ew0KICAiYWxnIjogIl**********' \
--header 'Cookie: ss-opt=temp; ss-id=QVhFixRMpD92y7HQ7b74; ss-pid=De9QBzZCTdhmCdDFuftm'
curl --location --request DELETE 'https://lendingsandbox.crbcos.com/Hooks/v2/Registrations?id=eb62ffbd-7ed4-4146-be48-7f2a46551c0e' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ew0KICAiYWxnIjogIl**********' \
--header 'Cookie: ss-opt=temp; ss-id=QVhFixRMpD92y7HQ7b74; ss-pid=De9QBzZCTdhmCdDFuftm'
﻿
Required query parameter
Parameter name
Parameter type
Data type
Description
id
query
long
The registration ID of hook registration to remove
Sample response in JSON - DEL /Hooks/v2/Registrations
There is no response in the image below because the hook registration was deleted successfully.
﻿
You can use the Arix test collection in Postman to practice unregistering from an event:
In the Postman collection, Delete Registration click the tab, Params.
In the KEY field, enter id .
In the VALUE field, enter the registration ID number that you received when you registered to the event.
Click Send.
﻿
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
Parameter name	Parameter type	Data type	Description
id	query	long	The registration ID of hook registration to remove
Card parameters
Webhook events