Learning Central

Client Services

North America

clientsupport@svb.com
1.800.774.7390 | 408.654.4636
5:00 AM – 5:30 PM PT M-F

United Kingdom

ukclientservice@svb.com
0800.023.1441 | +44.207.367.7881
8:00 AM – 1:30 AM GMT

Bill Pay Classic

1.866.321.6563
4:30 AM PT - 11:00 PM PT M-F

Card Services

Cards Issued in the U.S.

cardservices@svb.com
1.866.553.3481
001.408.654.1039 (international)

Cards Issued in the UK
Support, lost, or stolen

0800.023.1062
+44.0.207.367.7852 (international)

Elite Cards

1.866.940.5920 | 408.654.7720

Lost or Stolen Cards

1.844.274.0771
001.408.654.1039 (international)

FX Trade Desk

North America

1.888.313.4029
IntFXT@svb.com
5:00 AM PT – 4:00 PM PT

United Kingdom

+1.44.0.207.367.7880
ukfxtraders@svb.com
8:00 AM BST – 5:OO PM BST

SVB Asset Management

1.866.719.9117
samoperations@svb.com

SVB Cash Sweep

1.800.774.7390 | 408.654.4636
clientservice@svb.com

More Support Contacts

Webhooks

The SVB Webhooks API is currently in Beta and is subject to change.

This is the official reference documentation for the SVB Webhooks API. Please see the authentication documentation for access information.

The Webooks API follows the same conventions as SVB’s other APIs. Please see the documentation on API conventions for more information.

Background

The Event object represents a change of state to an api object. Each event type will have a specialized schema to best describe the changes to the object.

The Webhooks object represents information on how to communicate to an api user about useful api events. Allowing the api to contact the api user, bypassing the need of constant polling by the api user.

Webhooks are signed using a similar HMAC schema as found in the authentication documentation. A few minor differences exist noted below.

The signature is calculated using the following fields:

FIELD TYPE VALUE EXAMPLE
secret string The HMAC secret key. FNAqNywCi0hmo845Ni43p06mx3l4ub7C
timestamp int The number of seconds since the Unix epoch. 1490041002
method string The HTTP method as an upper case string. POST
url string The callback url of the webhook, must use https. https://www.api-svb.com/svb-webhooks
body string The body of the request. See example test webhook body.

Using this algorithm:

  1. Let + be a function that concatenates strings, and let "\n" indicate a newline character;
  2. Let HMAC be a function that calculates an HMAC from a string and a secret key, and let HEX be a function that returns the string hexadecimal representation of its input; then
  3. The signature is:
  HEX( HMAC( your_secret_key,
             timestamp + "\n"
             method + "\n" +
             url + "\n" +
             body ))

For more information on HMAC signing, see the section on authentication documentation.

Events 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.
4 “onboarding.company.status” Triggered when the status of an onboarding company changes.
5 “ach.status” Triggered when an ach transfer fails.
6 "virtualcard.realtime.auths" Triggered when authorization notification is received from MasterCard.
7 "ach.$$limit.exceeded" Triggered when the ach limit is exceeded.
8  "virtualcard.clearings" Triggered when a clearing notification is received from MasterCard.

 

List all Event Types

Request:

GET /v1/events/types

Response:

200 OK List of event type resources.

Example request:

curl "https://api.svb.com/v1/events/types" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": [
    {
      "id": 7,
      "name": "virtualcard.clearings"
    },
    {
      "id": 6,
      "name": "virtualcard.realtime.auths"
    },
    {
      "id": 5,
      "name": "ach.status"
    },
    {
      "id": 4,
      "name": "onboarding.company.status"
    },
    {
      "id": 3,
      "name": "virtualcard.deleted"
    },
    {
      "id": 2,
      "name": "virtualcard.created"
    },
    {
      "id": 1,
      "name": "all"
    }
  ]
}

Events

Event objects encapsulate detailed changes on an api object.

Attributes

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": "/v1/events/101"
}

 


Retrieve an Event

Request:

GET /v1/events/:id

Response:

200 OK The event resource.

Example request:

curl "https://api.svb.com/v1/events/123" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": {
    "id": "123",
    "created_at": "2017-21-08T13:19:09.776Z",
    "event_type": "all",
    "payload": {
        "id": "201",
        "status": "failed"
    },
    "type": "event",
    "url": "/v1/events/123"
  }
}

 


List all Events

Request:

GET /v1/events

Response:

200 OK List of events resources.

Example request:

curl "https://api.svb.com/v1/events" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

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

 

Webhooks

Webhook objects consist of a url to which to post events occuring on the api.

Attributes

NAME TYPE DESCRIPTION
id string Uniquely identifies each webhook object.
event_type_ids int array Ids of event types which cause webhook to trigger.
secret string Key used for HMAC signing of request.
status enum(active,inactive) Only active webhooks will be triggered.
callback_url string Url to post requset to, must use https.

Example Webhooks object:

{
    "id": "101",
    "event_type_ids": [1],
    "secret": "qwertyuipasdfghjklzxcvbnm1234567890",
    "status": "active",
    "callback_url": "https://www.somewhere.com/svb-webhooks",
    "type": "webhook",
    "url": "/v1/webhooks/101"
}

 


Create a Webhook

Request:

POST /v1/webhooks

Parameters:

NAME TYPE REQUIRED (?) DESCRIPTION
event_type_ids int array   Ids of event types which cause webhook to trigger.
secret string   Key used for HMAC signing of webhook requests.
status enum(active,inactive)   Only ‘active’ webhooks will be triggered.
callback_url string R Url to post requset to, must use https.

Response:

200 OK The new webhook resource.

Example request:

curl "https://api.svb.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
        "data": {
          "callback_url": "https://www.somewhere.com/svb-webhooks",
          "event_type_ids": [1],
          "secret": "qwertyuipasdfghjklzxcvbnm1234567890",
          "status": "active"
        }
      }'

Example response:

{
  "data": {
    "id": "123",
    "callback_url": "https://www.somewhere.com/svb-webhooks",
    "event_type_ids": [1],
    "secret": "qwertyuipasdfghjklzxcvbnm1234567890",
    "status": "active",
    "type": "webhook",
    "url": "/v1/webhooks/123"
  }
}

 


Retrieve a Webhook

For security reasons the hmac secret field is only returned on create.

Request:

GET /v1/webhooks/:id

Response:

200 OK The webhook resource.

Example request:

curl "https://api.svb.com/v1/webhooks/123" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": {
    "id": "123",
    "callback_url": "https://www.somewhere.com/svb-webhooks",
    "event_type_ids": [1],
    "secret": null,
    "status": "active",
    "type": "webhook",
    "url": "/v1/webhooks/123"
  }
}

 


Update a Webhook

Request:

PATCH /v1/webhooks/:id

Parameters:

NAME TYPE REQUIRED (?) DESCRIPTION
event_type_ids int array   Ids of event types which cause webhook to trigger.
status enum(active,inactive)   Only 'active’ webhooks will be triggered.

Response:

200 OK The updated webhook resource.

Example request:

curl "https://api.svb.com/v1/webhooks/123" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -X PATCH \
    -d '{
          "data": {
            "active": "inactive"
          }
        }'

Example response:

{
  "data": {
    "id": "123",
    "callback_url": "https://www.somewhere.com/svb-webhooks",
    "event_type_ids": [1],
    "secret": null,
    "status": "inactive",
    "type": "webhook",
    "url": "/v1/webhooks/123"
  }
}

 


Delete a Webhook

Request:

DELETE /v1/webhooks/:id

Response:

204 No Content

Example request:

curl "https://api.svb.com/v1/webhooks/123" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -X DELETE


List all Webhooks

Request:

GET /v1/webhooks

Response:

200 OK List of webhook resources.

Example request:

curl "https://api.svb.com/v1/webhooks" \
    -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": [
    {
      "id": 123,
      "type": "webhooks",
      "url": "/v1/webhooks/123"
    },
    {
      "id": 122,
      "type": "webhook",
      "url": "/v1/webhooks/122"
    },
    {
      "id": 121,
      "type": "webhook",
      "url": "/v1/webhooks/121"
    }
  ],
  "links": {
    "first": "/v1/webhooks",
    "next": null
  }
}

 


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 /v1/webhooks/:id/test

Response:

200 OK Test webhook resource response.

Example request:

curl "https://api.svb.com/v1/webhook/123/test" \
    -H "Authorization: Bearer YOUR_API_KEY"

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"
  }
}