Introduction
Webhooks allow SVB clients to receive event notifications on their SVB API activity. Clients can listen for events, get notified of updates on their payment activity in real-time and react on the received updates.
What is a webhook
SVB webhook notification is an API driven one-way data sharing capability that is triggered by an event. Users receive HTTP callback notifications on previously subscribed event types.
Use case - ACH API
Once an API request is submitted on the ACH API, there are various statuses that a payment can move into. The client will generally need to check for any changes by polling the API endpoint.
This is no longer needed if the webhook subscription is in place to receive ACH payment status updates. The client can:
- Subscribe to ACH payment status event type.
- Receive event notifications by SVB when the payment status changes.
- Integrate their internal system to update payment status and react appropriately to the received event notifications.
Steps to configure a webhook
- Based on the SVB product being used, client identifies the list of event types that they are interested in.
- Client authenticates with the Authentication API and receives an access token.
- Client subscribes to event types, specifying where they want to receive the callback notifications.
- Once SVB processes the appropriate events to trigger the webhook, SVB informs the client at the callback address specified on the subscription.
Retries
If delivery of the event notification fails for any reason, SVB will retry to send the event notification at a later time. Below are the retry intervals to resend a failed event notification.
| Attempt | Time |
|---|---|
| First Attempt | 2 seconds |
| Second Attempt | 4 seconds |
| Third Attempt | 8 seconds |
| Fourth Attempt | 16 seconds |
After above attempts are exhausted, SVB will repeat the process again for 3 more times with an interval of 1 hour. After 4 retries, if the event notification is still not sent then the notification status will be updated to "FAILED".
Technical Integration
1 - Authentication
Webhooks use the same authentication mechanism as ACH v2, Wires and VCN v2 APIs. More information on SVB oAuth 2.0 can be found on the authentication page.
2 - Event Types
Clients can subscribe to below event types. Subscription to multiple event types and multiple subscriptions to same event type are both allowed.
| API Product | Event Name | Description |
|---|---|---|
| ACH | ach.statuscritical | Triggers events for returns or corrections on ACH transfers. |
| ACH | ach.statusadvice | Triggers for non-critical events on ACH transfers, changes from one status to another (i.e. updates to statuses: processing, successful, canceled). |
| ACH | ach.information | Effective date adjustments on the submitted ACH API request (i.e. changing effective date of original request due to a holiday). |
| Wires | wires.status | Status changes of a wire payment. |
| VCN | vcn.created | Notification when a virtual card is created using the VCN API. |
| VCN | vcn.canceled | Notification when a virtual card is cancelled using the VCN API. |
| VCN | vcn.clearings | Notification when a virtual card clearing is received for a transaction. |
| VCN | vcn.authorizations | Notification when a virtual card authorization is received for a transaction. |
3 - Subscription
Subscription to the event type can be made using the endpoint: /v2/event/subscriptions
As the client obtains their "access_token" and "jws-signature", POST call can be made to create a subscription to the webhook event.
access_token is set using Authorization: Bearer Token
JWS signature token is included in the header (note: request body of the JWS token call must match the request body of the actual subscription request below)
Optional Encryption - To Verify the Sender of an Event Notification
Clients have the option to specify a secret key to encrypt and generate a signature for the event notification.
- As the event notification is received, the client can generate their signature using the same algorithm and compare this signature against the signature specified on the received webhook event.
- If the two signatures match, the sender of the event notification can be confirmed.
- More information can be found on the Signature Verification section.
4 - Receiving Event Notification
Once step 3 is completed, the integration is complete. Clients will start listening for events on the callback address that they used to subscribe for the event type in step 3.
Below is an example of such event (ach.information), arriving at the callback address specified by the client. Please see further examples here
5 - Signature Verification (Optional)
Once the client receives an event notification (as in step 4), the client can then fetch the HmacSHA256 encrypted signature from the header (named X-Signature).
This signature will then be compared against the signature client generates as below:
- Client will generate an encrypted signature using HmacSHA256 algorithm with parameters: timestamp, http method, callback url and event notification payload.
Sample Java Signature Verification Code
String timeStamp = request.getHeader("x-timestamp")
String httpMethod = "POST"
String callbackUrl = { clientCallbackUrl }
String payload = { receivedNotificationPayload }
String data = new String().join("\n", timeStamp, httpMethod, callbackUrl, payload));
String key = { clientSecretKey }
String signature = new HmacUtils(HmacAlgorithms.HMAC_SHA_256, key).hmacHex(data);
String incomingSignature = request.getHeader("x-signature");
if(signature.equals(incomingSignature) {
// consume and process notification
} else {
// sender of the notification cannot be verified
}Example Event Notifications
ACH
1 ach.information
=================
Example :
{
"data": {
"event_id": "aaaaaaaa-cbbb-482d-9c4d-dccb7831e680",
"event_type_name": "ach.information",
"created_at": "2022-08-10T22:44:59.429148Z",
"payload": {
"delta": [
{
"field_name": "effective_entry_date",
"old_value": "2022-08-10",
"new_value": "2022-08-11"
}
],
"ach_transfers_id": "aaaaaaaa-193b-4040-b579-cc897a9cc4c2",
"modified_at": "2022-08-10T22:44:59.299728Z"
}
}
2. ach.statusadvice : PENDING -> PROCESSING
===========================================
{
"data": {
"event_id": "aaaaaaaa-e461-4a7e-b425-fde3341cf2b0",
"event_type_name": "ach.statusadvice",
"created_at": "2022-08-10T22:53:41.855917Z",
"payload": {
"delta": [
{
"field_name": "status",
"old_value": "PENDING",
"new_value": "PROCESSING"
}
],
"ach_transfers_id": "aaaaaaaa-6c23-4ba4-a4e3-e7fcc3c86dc7",
"modified_at": "2022-08-10T22:53:41.459418Z"
}
}
}
3. ach.statusadvice : PROCESSING -> SUCCEEDED
===========================================
{
"data": {
"event_id": "aaaaaaaa-e461-4a7e-b425-fde3341cf2b0",
"event_type_name": "ach.statusadvice",
"created_at": "2022-08-10T22:53:41.855917Z",
"payload": {
"delta": [
{
"field_name": "status",
"old_value": "PROCESSING",
"new_value": "SUCCEEDED"
},
{
"field_name": "fed_trace_number",
"new_value": "111111111111111"
],
"ach_transfers_id": "aaaaaaaa-6c23-4ba4-a4e3-e7fcc3c86dc7",
"modified_at": "2022-08-10T22:53:41.459418Z"
}
}
}
4. ach.statuscritical : PROCESSING -> FAILED
============================================
{
"data": {
"event_id": "aaaaaaaa-e461-4a7e-b425-fde3341cf2b0",
"event_type_name": "ach.statuscritical",
"created_at": "2022-08-10T22:53:41.855917Z",
"payload": {
"delta": [
{
"field_name": "status",
"old_value": "PROCESSING",
"new_value": "FAILED"
},
{
"field_name": "return_code",
"new_value": "RO1"
}
],
"ach_transfers_id": "aaaaaaaa-6c23-4ba4-a4e3-e7fcc3c86dc7",
"modified_at": "2022-08-10T22:53:41.459418Z"
}
}
}
5. ach.statuscritical : PROCESSING -> CORRECTED
============================================
{
"data": {
"event_id": "aaaaaaaa-e461-4a7e-b425-fde3341cf2b0",
"event_type_name": "ach.statuscritical",
"created_at": "2022-08-10T22:53:41.855917Z",
"payload": {
"delta": [
{
"field_name": "status",
"old_value": "PROCESSING",
"new_value": "CORRECTED"
},
{
"field_name": "return_code",
"new_value": "CO1"
},
{
"field_name": "corrected_data",
"new_value": "999999999"
}
],
"ach_transfers_id": "aaaaaaaa-6c23-4ba4-a4e3-e7fcc3c86dc7",
"modified_at": "2022-08-10T22:53:41.459418Z"
}
}
}
Virtual Card (VCN)
1. vcn.created
======================
{
"data": {
"event_id": "aaaaaaa6-ba18-411a-933c-c08be4f34a48",
"event_type_name": "vcn.created",
"created_at": "2022-08-10T22:53:21.079193Z",
"payload": {
"id": "76aaaaaa-88ef-4b1b-be5a-603a28f939b9",
"status": "APPROVED",
"rcn_id": "4440",
"rcn_alias": "AAARCN",
"valid_starting_on": "2022-08-09",
"valid_ending_on": "2022-12-12",
"available_balance": 70000,
"total_card_amount": 70000,
"transactions_max": 1000,
"per_transaction_max": 70000,
"per_transaction_min": 0
}
}
}
2. vcn.canceled
===================
{
"data": {
"event_id": "aaaaaaa6-1cbf-484b-adb3-ad2ab3089da0",
"event_type_name": "vcn.canceled",
"created_at": "2022-08-10T23:24:41.571761Z",
"payload": {
"id": "0e85babb-c650-4e19-9157-fa07e126e13b",
"status": "CANCELED"
}
}
}
3. vcn.clearings
========================
{
"data": {
"event_id": "aaaaaaa6-2953-47a7-a733-819651713719",
"event_type_name": "vcn.clearings",
"created_at": "2022-08-11T19:37:57.606678Z",
"payload": {
"rcn_id": "4440",
"rcn_alias": "AAARCN",
"MCC": "22",
"vcn_id": 1234567,
"MerchantId": "03-00000869",
"AcquirerICA": "",
"ApprovalCode": "028937",
"ClearingType": "DEBIT",
"MerchantName": "ACME1",
"BillingAmount": "100",
"MCCDescription": "ELECTRONIC SALES",
"MerchantAmount": "100",
"SettlementDate": "2022-01-20T00:00:00.000Z",
"AuthorizationDate": "2022-01-19T00:00:00.000Z",
"BillingCurrencyCode": "GBP",
"MerchantCurrencyCode": "GBP",
"TxnExchangeRate": "1.000000",
"card_number": "556338######1234",
"BanknetReferenceNum": "000ABCDEFGHI",
"MasterCardFinancialTransactionId": "0000000001234",
"AcquirerReferenceData": "85481472020000000001234",
"vcn_uuid": "aaaaaaa6-3391-4c75-80ce-93957988774b"
}
}
}
4. vcn.authorizations
========================
{
"data": {
"event_id": "aaaaaaa6-8bd4-4d19-9e97-e67a91da1f9c",
"event_type_name": "vcn.authorizations",
"created_at": "2022-08-11T19:16:56.706665Z",
"payload": {
"rcn_id": "4440",
"rcn_alias": "Travel Expense RCN",
"MCC": "5542",
"vcn_id": 1234567,
"MerchantId": "03-00000869",
"ApprovalCode": "502359",
"MerchantName": "AMCE2",
"BillingAmount": "7550",
"MCCDescription": "FUEL DISPENSER AUTOMATED",
"MerchantAmount": "7550",
"BillingCurrencyCode": "USD",
"MerchantCurrencyCode": "USD",
"card_number": "************6213",
"BanknetReferenceNum": "A",
"vcn_uuid": "aaaaaaa6-4eac-4708-acb0-0b16fe4ce5fd",
"AdviceReasonCode": "650",
"CompanyId": 123456,
"IssuerResponse": "Approved",
"MerchantCity": "Jasper",
"MerchantStateOrCountryCode": "TN",
"MessageTypeIndicator": "Unknown message type indicator: 9110",
"PurchaseRequestCompanyGuid": "AAAAAA995197AAAAAA206CB494B560E5AAAAAA2A2BD21D89612EF4A18358ECC777DCF1494921797",
"PurchaseRequestIssuerGuid": "AAAAAA5E4C4B4AAAAAA5991E64A1E0745AAAAAAB2510CE48EB537011DCED3C483669D61494938440",
"ReplacementAmountsTransactionAmount": 1200,
"ReplacementAmountsSettlementAmount": 1200,
"ReplacementAmountsBillingAmount": 1200,
"SystemTraceAuditNumber": "011111",
"TransactionDateTime": "2022-11-03T10:16:11Z",
"VcnResponse": "Valid",
"ClearingReferenceNumber": "A"
}
}
}