Registrations

Overview

Webhook registrations map your endpoints to COS event types. You can only have one registration per event type. If you require the event be sent to multiple endpoints, it is recommended you perform that secondary routing in a single endpoint you setup. The first step to using webhooks is to create a new registration resource.

Push Registrations

The most common, and default, registration type is Push. This is indicating you want the event to be delivered as a traditional webhook to the URL of the endpoint you've setup to process it. Push registrations are the recommended choice for webhook delivery.

POST /webhooks/v1/registrations
{
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "eventName": "Core.Account.Opened",
  "type": "Push", 
  "callbackUrl": "https://cos.yourcompanysite.com/account-events",
  "authUsername": "some_user",
  "authPassword": "secret_password",
  "format": "Basic"
}

📘

Testing Registrations

If you want to test that your registration is working, simply call the /ping endpoint. It will simulate a webhook event to your callback URL with an empty resources collection. In addition, the isPing flag will be set to make it easy to handle the event appropriately.

More details can be found in the API reference

Poll Registrations

There are times when traditional Push events aren't ideal or even possible, and polling is preferred instead. Polling works by searching a list of pending events via the API, processing them, and finally calling acknowledge for each event processed via the API.

POST /webhooks/v1/registrations
{
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "eventName": "Core.Account.Opened",
  "type": "Poll",
  "format": "Basic"
}

After registering that you wish to receive a particular event in a polling manner, you would then call the poll events API endpoint periodically. This will return the next pending event waiting for acknowledgement.

GET /webhooks/v1/events/poll

{
      "id": "00000000-0000-0000-0000-000000000000",
      "eventName": "Core.Account.Opened",
      "status": "Pending",
      "partnerId": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2019-11-04T17:12:34.806Z",
      "lastAttemptedAt": "2019-11-04T17:12:34.806Z",
      "resources": [
        "https://sandbox.crbcos.com/core/v1/dda/accounts/1234567890",
        "https://sandbox.crbcos.com/core/v1/dda/accounts/1234567891"
      ],
      "isPing": false
}

Finally the last step would be to acknowledge the event you've processed. Acknowledging an event will cause the status to go from Pending to Success.

POST /webhooks/v1/events/{id}/acknowledge

Simply repeat the process on a periodic polling schedule of your choice. It is generally not recommended to poll more frequently than once every 30 seconds.

File Registrations

File registrations are similar to Poll registrations, however they are not available in real-time. Instead they are delivered via SFTP in a CSV file once per day. The events are auto-acknowledged, so there is no need to call the API when processing these events. Note that in addition to registering via the API, coordination with our data team is required to set up this type of delivery.

POST /webhooks/v1/registrations
{
  "partnerId": "00000000-0000-0000-0000-000000000000",
  "eventName": "Core.Account.Opened",
  "type": "File",
  "format": "Basic"
}

See API reference for more details.

Delete Registrations

You can easily delete your webhook registrations using the event registration ID. This should only be used when you no longer wish to receive a particular webhook event.

DELETE /webhooks/v1/registrations/{id}

A successful response code of 200 confirms that your registration has been deleted.

Authentication

COS optionally supports basic authentication on each registration. You may supply an AuthUsername and AuthPassword which will be base64 encoded and included as an Authorization header on each webhook you receive.

Note that the preferred security practice is to use webhook signature verification instead of basic authentication.

Extended Format

📘

Keep it Simple

Only use Extended format if you have a real need. Most of the time Basic format is all that is required to handle an event. Plus, with Basic format you will receive up to 50,000 events per payload versus just 1,000 with Extended format.

COS supports two different event formats: Basic and Extended. Basic is the default and will only deliver an array of resource identifiers relating to the given event. Usually this is enough for processing, and is preferred since it results in smaller payloads being delivered. The Extended format will give you everything found in the basic format; in addition it includes a Details array of meta data which varies by event type. For example, ACH.Return.Received will include meta data such as the return code and original payment ID. This is included to allow processing without the need to look up the return payment record via an API call in order to extract those details. This format should only be used in cases where the need for these details exist, since payloads can be quite large and fewer event resources will be delivered per event.