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.

Frequently Asked Questions

Try it Out

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 amount, banknet_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

Table of Contents

Event Types

Events

Test a Webhook

Webhook Retries