Webhook events and subscriptions

What type of webhook events do we support and how do you subscribe to these events.

For an overview, see Webhooks. ▶ Run in Postman

To be sent an event notification, you need to subscribe to the required event. You can subscribe to more than one event.

For example, subscribing to kyc.verification.success enables you to receive the successful result of a customer KYC verification request once it has finished being processed.

See /webhooks in the Bond API reference to see the specification on this endpoint.

Event types

The events that you can subscribe to are shown in the table below.

Event enum valuesDescription
kyc.verification.errorKYC failed due to server error.
kyc.verification.failureKYC failed due to low confidence in identity validation.
kyc.verification.successKYC passed.
kyc.verification.timeoutThe system timed out trying to verify the information. Run KYC again.
kyc.verification.document_requiredKYC requires further information to continue. This includes a documents field that indicates the types of documents required.
kyc.verification.under_reviewKYC documents submitted are being reviewed.
kyc.verification.reenter_informationThis is optional and will be sent at the same time as kyc.verification.document_required

The customer may have entered incorrect information that can cause KYC failure. Reentering this information may resolve the issue. This includes an incorrect_information field that identifies exactly what should be checked by the customer.
transactionsSent on every new transaction or transaction update.
account.history.readyThis is used when retrieving an external account history for the first time.
card.createdCard has been created.
card.status.activeCard status is now Active.
card.status.closedCard status is now Closed.
card.status.fraudCard status is now Fraud.
card.status.inactiveCard status is now Inactive.
card.status.lostCard status is now Lost.
card.status.reissueCard status is now Reissue.
card.status.stolenCard status is now Stolen.
card.wallet.addCard was successfully added to a mobile wallet.
card.wallet.add_failure Card failed to be added to a mobile wallet.
kyb.verification.errorKYB failed due to server error.
kyb.verification.approvedKYB passed.
kyb.verification.rejectedKYB failed due to low confidence in identity validation.
kyb.verification.warningRun KYB again.
kyb.verification.initiatedKYB process has been initiated.

Subscribe to an event

To set up an active event subscription, pass a list containing one or more event labels that you want to be informed of to the webhooks API. For details, see Managing subscriptions.

The response contains a unique webhook "secret" string that you should store securely. This string is used to verify the signature of requests from the webhooks API to the provided callback URL and can be retrieved at any time using the webhooks API.

A response to a successful webhook subscription request is shown below.

{
  "date_created": "2020-11-17T11:13:06.568119",
  "webhook_id": "522e9ec7-b17d-4d92-8270-c2e1741dd6e0",
  "callback_url": "https://hostname.com/webhook/route",
  "description": "KYC state changes",
  "events": [
    "kyc.verification.status"
  ],
  "status": "enabled",
  "secret": "whsec_XqTEJtniwuEhp0A1c1cTJNsmpR/qgOfB"
}

Transaction event example

The transaction event example shown below sends notifications of every transaction type across card transactions, in addition to the ACH, and RCD transactions to the call-back URL provided.

curl --request POST 'https://api.bond.tech/api/v0/webhooks/' \
--header 'Identity: YOUR-IDENTITY' \
--header 'Authorization: YOUR-AUTHORIZATION' \
--header 'Content-Type: application/json' \
--data-raw '{"events":["transactions"],"callback_url":"https://hostname.com/webhook/route","description":"Return Transactions"}'
import requests

url = "https://sandbox.bond.tech/api/v0/webhooks/"

payload = {
    "events": ["transactions"],
    "callback_url": "https://hostname.com/webhook/route",
    "description": "Return Transactions"
}
headers = {
    "Content-Type": "application/json",
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0/webhooks/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'
request.body = "{\"events\":[\"transactions\"],\"callback_url\":\"https://hostname.com/webhook/route\",\"description\":\"Return Transactions\"}"

response = http.request(request)
puts response.read_body
fetch("https://sandbox.bond.tech/api/v0/webhooks/", {
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
  },
  "body": "{\"events\":[\"transactions\"],\"callback_url\":\"https://hostname.com/webhook/route\",\"description\":\"Return Transactions\"}"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});
var client = new RestClient("https://sandbox.bond.tech/api/v0/webhooks/");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Identity", "YOUR-IDENTITY");
request.AddHeader("Authorization", "YOUR-AUTHORIZATION");
request.AddParameter("application/json", "{\"events\":[\"transactions\"],\"callback_url\":\"https://hostname.com/webhook/route\",\"description\":\"Return Transactions\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"events\":[\"transactions\"],\"callback_url\":\"https://hostname.com/webhook/route\",\"description\":\"Return Transactions\"}");
Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/webhooks/")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

Response response = client.newCall(request).execute();

As shown below, a successful 200 response indicates that the subscription is enabled and active.

{
  "event": "transaction",
  "transaction": {
      "transaction_id": "23d8d934-8830-4b8e-bbf4-479c1a2c3cdd",
      "previous_transaction_id": "1a805e9c-d22e-4f7d-87b2-8d148abecab6",
      "transaction_type": "purchase",
      "payment_type": "ach",
      "state": "failed",
      "customer_id": "60e69877-d703-4e66-8214-9313c9b29694",
      "account_id": "8bfa28ce-ab78-4f4c-ba4b-a18a729dd366",
      "amount": "155.33",
      "currency": "USD",
      "created_time": "2020-05-17T10:44:35.123421+00:00",
      "balances": {
        "prior_balance": "10.00",
        "new_balance": "10.00"
       },
      "details": {
        "card_id": "03aac4d6-8b17-4299-b7f9-b6fc8d71ebf6",
        "external_account_id": "68a87bb5-a4e6-4a29-a933-b8ee04704d8e",
        "class_code": "web",
        "direction": "debit",
        "network": "same-day-ach",
        "description": "Brand Trans.",
        "failure_reason": "Insufficient Funds",
        "return_code": "R01"
      }
   }
}

For a complete specification and interactive examples, see Webhooks in the Bond API Reference.