Webhooks
This is the official reference documentation for the SVB Webhooks API. Please see the authentication documentation for access information.
The Webhooks API follows the same conventions as SVB’s other APIs. Please see the documentation on API conventions for more information.

NOTE: this section on Webhooks (v2) pertains only to ACH v2 and Wires. Please also see the Webhooks (v1) information for ACH v1 and VCN v1

Event Types

Each event type designates a specific change to an api object. The event type describes the api object being changed as well as the change occurring.
 

ID NAME DESCRIPTION 
 1  all  Matches all event types.
 2  virtualcard.created  Triggered when a new virtual card is created.
 3  virtualcard.deleted  Triggered when a virtual card is cancelled.
 5  ach.status  Triggered when an ACH transfer fails.
 6  virtualcard.realtime.auths  Triggered when authorization notification is received from MasterCard.
 8  virtualcard.clearings  Triggered when a clearing notification is received from MasterCard.
 10

 virtualcard.realtime.iccp.all

 Triggered when realtime authorization, advice or reversal notification is received from MasterCard ICCP.
 13  ach.status.advice  Triggered for non-critical ACH status updates (status other than failed or corrected).

 

Events

Event objects encapsulate detailed changes on an api object.

 

NAME TYPE DESCRIPTION 
 id  string  Uniquely identifies each event object.
 event_type  string  Name of event type (see event types).
 payload  object  Current state of the api object.
 previous  object  Previous state of the api object.
 created_at  datetime  Date and time event was created in default ISO 8601 format.

 

Both the payload and previous json fields will contain an id which refers to the api object whose data has changed. When previous is null, it indicates no previous version of the object exists and the api object was created.

Example Event object:

{
    "id": "101",
    "event_type": "all",
    "payload": {
        "id": "201",
        "status": "failed"
    },
    "previous": null,
    "created_at": "2017-21-08T13:19:09.776Z",
    "type": "event",
    "url": "/v2/events/101"
}

Filtering:

This endpoint supports filtering. Depending on the event type, below parameters can be used to filter list of queried events. For more details on filtering, please refer to documentation on Conventions page. 
 

PARAMETER RANGE SUPPORT

 merchant_amount

 Filter by range is supported

 approval_code

 N/A

 banknet_ref_num

 N/A

 billing_amount

 Filter by range is supported

 card_number

 N/A

 financial_network_code

 N/A

 mcc_description

 N/A
 mcc  N/A

 merchant_name

 N/A

 rcn_alias

 N/A
 rcn_id  N/A

 transaction_date_time

 Filter by range is supported

 transaction_type

 N/A
 vcn_id  N/A
 id  N/A
 status  N/A

 

Merchant amountbanknet_ref_num and transaction_date_time fields support searches by a range. Below is an example query using transaction_date_time parameter:

Example with filtering:

{{URL}}/v2/events?page[limit]=1000&
filter[payload.transaction_date_time]=[2020-07-10,2020-07-11]

Example response:
Header: "Prefer: return-minimal"

{
  "data": [
    {
      "id": 123,
      "type": "event",
      "url": "/v2/events/123"
    },
    {
      "id": 122,
      "type": "event",
      "url": "/v2/events/122"
    },
    {
      "id": 121,
      "type": "event",
      "url": "/v2/events/121"
    }
  ],
  "links": {
    "first": "/v2/events",
    "next": null
  }
}

Example response:



{

  "data": [
  {
    "created_at": "2018-10-23T19:15:28.976Z",
    "event_type": "ach.$$limit.exceeded",
           "id": 25473,
          "payload": {
           "id": 340455
      },
      "previous": null,
      "type": "event",
       "url": "/v2/events/25473"
    },
  
  {
      "created_at": "2020-08-17T02:03:11.205Z",
      "event_type": "virtualcard.realtime.auths",
      "id": 77012,
      "payload": {
           "acquirer_ica": "003286",
           "approval_code": "020936",
           "billing_amount": 4245,
           "billing_currency": "USD",
           "card_number": "556338######2882",
           "issuer_response": "Approved",
           "mcc": "8931",
           "mcc_description": "ACCOUNTING, AUDITING AND BOOKKEEPING SERVICES",
           "merchant_amount": 9090,
           "merchant_currency": "USD",
           "merchant_id": "242661000053360",
           "merchant_name": "SQ *DELTA TOWING SAN ANTONIO TX",
           "transaction_date_time": "2020-07-11T16:53:11.000Z",
           "transaction_type": "Authorization Advice",
           "vcn_id": 3090180,
           "vcn_response": "Valid"
      },
      "previous": null,
      "type": "event",
      "url": "/v2/events/77012"
    },
    {
      "created_at": "2019-10-25T10:20:03.696Z",
      "event_type": "ach.status",
      "id": 75773,
      "payload": {
           "id": 5956,
           "return_code": "R01",
           "status": "failed"
      },
      "previous": {
      "id": 5956,
      "return_code": null,
           "status": "processing"
      },
      "type": "event",
      "url": "/v2/events/75773"
    },
    {
      "created_at": "2020-08-18T19:22:22.680Z",
      "event_type": "onboarding.company.status",
      "id": 77083,
      "payload": {
           "id": 28827,
           "status": "pending"
      },
      "previous": null,
      "type": "event",
      "url": "/v2/events/77083"
    },
    {
      "created_at": "2020-08-18T19:22:07.671Z",
      "event_type": "virtualcard.created",
      "id": 77081,
      "payload": {
           "available_balance": 12345,
           "currency": "USD",
           "id": "3188156",
           "per_transaction_max": 12345,
           "per_transaction_min": 0,
           "rcn_alias": "Test Account 1",
           "rcn_id": 126507,
           "status": "Approved",
           "total_card_amount": 12345,
           "transactions_max": 41,
           "valid_ending_on": "2021-12-31",
           "valid_starting_on": "2020-08-17"
      },
      "previous": null,
      "type": "event",
      "url": "/v2/events/77081"
    }
  ]
}

Test a Webhook

To help aid in debugging whether a webhook has been configured correctly, the test route can be used to manually trigger a webhook.

The response status of the callback url will be returned.

Note: - both active and inactive webhooks will be triggered by the test route - event type ids attached to the webhook are ignored - a test type “webhooks.test” will be attached to the webhook payload - an event id of 0 will be attached to the payload, indicating test data - the payload data will return data from the webhook being tested

Request:

GET /v2/webhooks/:id/test

Response:

200 OK Test webhook resource response.

Example response:

{
  "data": {
    "status": 200
  }
}

Example test webhook request body:

{
  "data": {
    "date": "2017-08-21T16:34:26.330Z",
    "event-id": 0,
    "payload": {
        "id": 123,
        "callback_url": "https://www.api-svb.com/svb-webhooks",
        "event_type_ids": [1],
        "status": "active"
    },
    "type": "webhooks.test"
  }
}

Webhook Retries

Webhooks will be retried anytime we do not receive a successful response from the destination url/server, in other words, if we receive a 5xx response.  We will send the retries a total of 5 times with the following spacing: 

ATTEMPT TIME
First attempt 0
Second attempt  10minutes
Third attempt  28 minutes
Fourth Attempt  78 minutes
Fifth Attempt 108 minutes