Register for webhook events

Base Address

• https://lendingsandbox.crbcos.com

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

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
}'

🚧

Duplicate 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

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 imlemented 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": ""
    }
  }

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. Go to https://webhook.site.
2. Click New on the top menu.
   The site returns Your unique URL.
3. Copy to clipboard your unique URL.

Note: 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.