Accounts, cards and payment events

when you work with cross river accounts, card issuing, customer management and payments, you register for specific webhooks, unlike in card payments and lending where you register for a set of webhooks these events each return a resource object that contains relevant details about the subject of each event this eliminates the need to poll the api to discover changes the full event details are included and sent to your system the system typically aggregates event objects every 30 seconds important webhook delivery is guaranteed at least once while rare, it's technically possible to receive the same event twice your message handlers should account for that edge case and be idempotency event registration there are several ways to receive event notifications push webhook events that are reported to a registered partner endpoint (a callback url) poll webhook e vents that are reported after a partner polls the events api the post calls for the registration methods are the same make sure to select the correct registration type , either push or poll we recommend that you use push registration register for push events use post /webhooks/v1/registrations to register which includes defining the callback urls where event reports should be delivered important your system must respond to each push event with a 200 status to avoid getting suspended in this example, your partnerid identifies you as the entity requesting webhook registration to the eventname core account opened , which is a push registration the eventname is being registered to the callbackurl https //cos yourcompanysite com/account events sample webhook push registration { "partnerid" "8gj76s99 jhso 89as nsl8 119nss8ch7ab", "eventname" "core account opened", "type" "push", "callbackurl" "https //cos yourcompanysite com/account events", "authusername" "{username}", "authpassword" "{password}", "format" "basic" } important to confirm your callback url is registered, call put /v1/registrations{id}/ping it simulates a webhook event sent to your callback url but doesn't include any resources in addition, the isping flag will be set to make it easy to handle the event appropriately register to poll for events use post /webhooks/v1/registrations to register to poll for an event status we recommend you poll for events only if you're not able to receive webhooks via push in the example below, your partnerid identifies you as the entity requesting registration to be able to poll the eventname core account opened sample poll registration { "partnerid" "8gj76s99 jhso 89as nsl8 119nss8ch7ab", "eventname" "core account opened", "type" "poll", "format" "basic" } poll for events call get /webhooks/v1/events/poll to poll for events when you poll the system, the events are sent in status pending and every event has to be manually acknowledged don't poll more than once every 30 seconds in the example below, the eventname core account opened polls the deposit account resources https //sandbox crbcos com/core/v1/dda/accounts/ to check the registration status poll event response { "id" "g98sxnbv 9000 nks7 jjsy xn6554bv9h10", "eventname" "core account opened", "status" "pending", "partnerid" "8gj76s99 jhso 89as nsl8 119nss8ch7ab", "createdat" "2022 11 04t17 12 34 806z", "lastattemptedat" "2022 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 } attribute description id id of the event being polled eventname name of the event being polled status when polling for an event, the status will always be pending partnerid your id in the cross river system this id is in guid format createdat when the event was created lastattemtpedat when the last attempt was resources elements (such as an account number or an event name) that the event is reporting on isping acknowledging an event failing to acknowledge an event will cause the get /webhooks/v1/events/poll endpoint to respond with the same information call post /webhooks/v1/events/{id}/acknowledge to acknowledge that you received the event use the id you received when you checked the event status in this call when you acknowledge an event, the status changes from pending to success delete a registration use the event registration id you received when you polled the event to delete an event registration event delivery unsuccessful monitor the status of your webhook registrations event that we can't successfully deliver will expire after 7 days if the system can't deliver an event to one of your registrations, it makes several attempts to re send the event if we still can't deliver the event after several retries, its registration status changes to suspended and we start to queue all your events for your registration no further attempts are made to deliver previous or future events to this endpoint until your registration returns to an active status if there is an event delivery failure, don't delete a registration and re register for the same event this prevents you from retrieving any events that were queued for delivery, as well as any events that fired in the time between deletion and re registration if you get a suspended status, review the logs of recent failed events to identify the issue when the issue is resolved, restart your registration with the restart by id webhook api the status transitions to restarting if we can deliver an event successfully the status returns to active when the status returns to active we deliver all the queued events from when your registration status was suspended if we can't successfully deliver at least 1 event, the status returns to suspended when a suspended webhook is restarted, all queued webhook notifications are delivered immediately event status whenever you receive an event, it is always in pending status and refers to the event status (an event was created but not yet delivered), and not the resource status if you want to see if webhooks were delivered successfully, call get /webhooks/v1/events/{id} if the event was delivered successfully you will see status\ success authentication our system optionally supports basic authentication on each registration you can supply an authusername and authpassword which will be base64 encoded and included as an authorization header on each webhook you receive important the preferred security practice is to use webhook signature verification instead of basic authentication signatures every webhook is signed with a standard hmac with sha256 hash this provides an added layer of protection from replay attacks without a signature, an attacker could intercept a valid payload and retransmit it the signature can be found in the event's request header and includes the event timestamp our system generates a timestamp and signature each time we send an event to your endpoint if our system retries an event after a previous failure, we generate a new signature and timestamp for the new delivery attempt if a timestamp is subsequently changed, the signature is then invalid sample request header cos signature\ t 2019 04 02t11 33 26 6672036 04 00, v1 {secret} important if you receive an event with an old timestamp we recommend you discard or flag it the recommended tolerance between timestamp and time of delivery will vary by your application's requirements, but should usually be less than 20 minutes we do however, recommend special consideration for situations where there has been an extended outage at either party all signatures are version 1 (v1) any other schemes besides v1 should ignored the signature is a standard hmac with sha256 hash validating the signature extract the timestamp and signature from the cos signature header concatenate the timestamp with the event body with a period in between the two values (as illustrated below) compute an hmac with the sha256 hash function use the signing secret (provided by the integration team) as the key and use the string created in step #2 as the message also be sure to base64 encode the computed hash value compare the hash generated in step #3 with the signature extracted from the cos signature header if the hash and signature match, this is a valid request from cos compare the timestamp to the time received if the difference exceeds your tolerance for accepting messages, you can reject the message or flag it for further review sample timestamp and body concatenation 2019 04 02t11 33 26 6672036 04 00 {"id" "123","eventname" "core customer email added","partnerid" "123","createdat" "2019 04 02t11 33 26 04 00","resources" \["core/v1/cm/customers/123"]} example a node js script that shows how a webhook signature would typically be validated sample validation script const crypto = require('crypto'); function validatesignature(header, payload, signingsecret) { let headerparts = header split(','); let timestamp = headerparts\[0] replace('t ', ''); let signature = headerparts\[1] trim() replace('v1 ', ''); let secret buffer = buffer from(signingsecret, 'base64'); let hmac = new crypto createhmac('sha256', secret buffer); let hmac digest = hmac update(`${timestamp} ${payload}`, 'binary') digest('base64'); console log(hmac digest); return hmac digest === signature; } let payload = '{"id" "e7ead744 d6ff 4521 863d abab0176f849","eventname" "core transaction completed","status" 0,"partnerid" "d6b4c661 b38a 46a3 8963 a9a40131eacf","createdat" "2020 04 28t18 45 14 57 04 00","resources" \["core/v1/transactions/6aa7e3b2 3c85 4647 aa6f abab0176e18b"],"details" \[{"transactionid" "6aa7e3b2 3c85 4647 aa6f abab0176e18b","transactioncode" "account transfer","debitsubaccount" "2058112745","debitmasteraccount" "2058112745","debitresult" "ok","creditsubaccount" "2101120877","creditmasteraccount" "2101120877","creditresult" "ok","rail" "internal","railid" "0","amount" "100"}]}'; let signatureheader = 't 2020 04 28t18 45 15 6360965 04 00, v1\ mvgxdx1o1p8+yjwglbmxaxkragvlmglsppczsr/ly/w='; let secret = 'uvdwwb9hifz+5/8nmta5pxu6p1kxzcqmxpcnbrhivnuknbhigth8mvmld7fyovfhomcpho5qyn/3hhnj+6to6q=='; let result = validatesignature(signatureheader, payload, secret); console log(result); faq why is my webhook status suspended ? suspended status means that we could not successfully deliver an event to one of your registrations see webhooks for cos what is the retention period of webhooks? currently there is no limitation to the retention period what is the maximum number of resources included in a single webhook event? 50k for events received in basic format 1k for events in extended format how are webhook failures handled? after a delivery failure, cos will retry 3 additional times after approximately 30 60 seconds before your registration updates to a suspended status if we still can't deliver the event after several retries, its registration status changes to suspended and we start to queue all your events for your registration no further attempts are made to deliver previous or future events until your registration returns to an active status what is the ip address from which cos webhooks are sent? for sandbox it’s 66 206 202 40 and for production its 66 206 202 41