Hook notifications

overview hooks is a notification system, used in lending to update you on the status of your loan hooks report to your system with real time notifications when an event happens in lending 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 https //docs crossriver com/content/lending/hooknotifications htm# 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 cross river 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 payload delivery wrapper when an event is sent in the form of a webhook, there will always be a wrapper around the content the actual event will be in the json's content section example loanstatusupdated event inside wrapper { "mplid" "tst", "ignore" false, "content" { "id" 0, "loanid" "c1ee19e4 791c 4f38 b581 ae6d007692a6", "status" 5, "timestamp" "2022 04 04t07 13 08 5754408+00 00", "dateinserted" "0001 01 01t00 00 00+00 00" } } attribute description mplid string a 3 letter id for the partner ignore boolean true or false content json this is the actual content of the event being sent sample events loanstatusupdate this event is reported every time the status of a loan is changed { "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 { "mplid" "xxx", "loanid" " guid ", "createdate" "date", "failedrulesreasons" \[ { "rulename" "rule name", "rule" "some string", "data" "some string", "result" true, "failedcomplianceid" 67 } ] } loannoteadded this event is reported when a bank operator wants to send you a message about a specific loan this is a message from a human user { "subject" "your loan 11112652056066 has additional comments", "message" "this is a note sent from the manual review ui", "createdby" "apollack, crb", "createdon" "2024 09 29t10 16 00 2828498", "loanid" "e9ad35a8 a9fa 4334 995d b1e800eb3e17", "loannumber" "11112652056066", "mpldetails" "tst testing mpl", "uri" "https //lendingappsandbox crbcos com/loans/underwrite?query=eyjsb2fucyi6eyjmawx0zxiiont9lcjzzwfyy2gionsic2vhcmnoijoiztlhzdm1ytgtytlmys00mzm0ltk5nwqtyjflodawzwizzte3in19lcj2awv3vhlwzsi6ikxvyw5zin0=", "rulename" null, "data" null } attribute description subject string the title of the note being added message string message sent from a human user createdby string the username that sent the message, along with the company they work for createdon datetime when the note was created loanid string unique cross river identifier for the loan loannumber string unique identifier for the loan, as sent by the partner mpldetails string mplid and name of the partner uri s tring uri that links to the loan that was commented on, in the cos lending manual review ui this can only be opened in a whitelisted workstation rulename string internal cross river information data s tring internal cross river information railupdated this event is reported when there is a status update to a rail that was requested { "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" } loansalestatusupdated this event is reported when a loan sale status has changed { "mplid" "tst", "investor" "rotzehribit", "loanid" "048ef0f5 1c08 4f58 b3db b26e00b59d59", "status" 1, //this is the loansalestatus enum "timestamp" "2025 05 04t18 15 29 242132+00 00", "loantype" "hfs", "issuingbank" "crb", "partnerloannumber" "18848835471438", "principal" 5100, "interest" 0, "volumefee" 0, "fees" \[] } batchpurchasecompleted this message is sent when the purchase of a batch of loans is completed in selling { "mplid" "tst", "batchid" "b5f018a8 331f 4762 8418 b2dd00ad65b8", "loantype" null, "issuingbank" "crb", "investor" "rotzehribit", "totalprincipalcharged" 176500, "totalinterestcharged" 26537 16, "totalvolumefeecharged" 458 9, "totalachfeecharged" 0, "numofloanspurchased" 15, "numofloanspartiallypurchased" 0, "timestamp" "2025 05 14t10 36 07 4395183+00 00" } 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 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 { "version" "2 0", "issuccessful" true, "statuscode" 200, "result" { "id" "eb62ffbd 7ed4 4146 be48 7f2a46551c0e", "applicationname" "cos lending", "hookname" "loanstatusupdated", } } webhooks without authentication "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 "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 "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 { "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 { "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 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