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 KYCKYC - Know Your Customer. A standard banking risk assessment practice to prevent identity theft, money laundering, fraud, and terrorism by verifying customer identities and understanding their transaction habits. KYC is a mandatory requirement of legal compliance in the financial sector. 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 values | Description |
---|---|
| KYC failed due to server error. |
| KYC failed due to low confidence in identity validation. |
| KYC passed. |
| The system timed out trying to verify the information. Run KYC again. |
| KYC requires further information to continue. This includes a documents field that indicates the types of documents required. |
| KYC documents submitted are being reviewed. |
| This is optional and will be sent at the same time as The customer may have entered incorrect information that can. Reentering this information may resolve the issue. This includes an |
| Sent on every new transaction or transaction update. |
| This is used when retrieving an external account history for the first time. |
| Card has been created. |
| Card status is now |
| Card status is now |
| Card status is now |
| Card status is now |
| Card status is now Lost. |
| Card status is now |
| Card status is now |
| Card was successfully added to a mobile wallet. |
| Card failed to be added to a mobile wallet. |
| KYB failed due to server error. |
| KYB passed. |
| KYB failed due to low confidence in identity validation. |
| Run KYB again. |
| KYB 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 ACHACH - Automated Clearing House. The network that coordinates electronic payments and automated money transfers. ACH is a way to move money between banks without using paper checks, wire transfers, card networks, or cash., 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.
Updated 5 months ago