Managing subscriptions

Creating a subscription

To create a subscription, use the POST /webhooks operation and provide the parameters as shown in the table below.

Parameter

Type

Description

callback_url
required

String

URL to which the event should be sent.

description

String

Freeform description of the webhook's intended use, for example Jun 28 2021 KYC approved update.

events
required

Array of strings

One or more events to enable.
For a list of events, see Event types.

For a complete specification and interactive examples, see Creating a webhook subscription in the Bond API reference.

An example of a request to create a webhook subscription is shown below.

curl --request POST \
  --url https://sandbox.bond.tech/api/v0/webhooks/ \
  --header 'Authorization: YOUR-AUTHORIZATION' \
  --header 'Content-Type: application/json' \
  --header 'Identity: YOUR-IDENTITY' \
  --data '{"events":["kyc.verification.success"],"callback_url":"https://technolaser.com/webhook","description":"KYC state change"}'
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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'
request.body = "{\"events\":[\"kyc.verification.success\"],\"callback_url\":\"https://technolaser.com/webhook\",\"description\":\"KYC state change\"}"

response = http.request(request)
puts response.read_body
const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  },
  body: JSON.stringify({
    events: ['kyc.verification.success'],
    callback_url: 'https://technolaser.com/webhook',
    description: 'KYC state change'
  })
};

fetch('https://sandbox.bond.tech/api/v0/webhooks/', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

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

payload = {
    "events": ["kyc.verification.success"],
    "callback_url": "https://technolaser.com/webhook",
    "description": "KYC state change"
}
headers = {
    "Content-Type": "application/json",
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

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

print(response.text)
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\":[\"kyc.verification.success\"],\"callback_url\":\"https://technolaser.com/webhook\",\"description\":\"KYC state change\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"events\":[\"kyc.verification.success\"],\"callback_url\":\"https://www.technolaser.com/webhook\",\"description\":\"KYC state change\"}");
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();

An example of a response to a successful request to create subscription is show below.

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

Retrieving all subscriptions

To retrieve a list of all webhook subscriptions, use the GET /webhooks.

An example of a request to retrieve a list of all subscriptions is shown below.

curl --request GET \
  --url https://sandbox.bond.tech/api/v0/webhooks \
  --header 'Authorization: YOUR-AUTHORIZATION' \
  --header 'Identity: YOUR-IDENTITY'
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

request = Net::HTTP::Get.new(url)
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'

response = http.request(request)
puts response.read_body
const options = {
  method: 'GET',
  headers: {
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  }
};

fetch('https://sandbox.bond.tech/api/v0/webhooks/', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

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

headers = {
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

response = requests.request("GET", url, headers=headers)

print(response.text)
var client = new RestClient("https://sandbox.bond.tech/api/v0/webhooks/");
var request = new RestRequest(Method.GET);
request.AddHeader("Identity", "YOUR-IDENTITY");
request.AddHeader("Authorization", "YOUR-AUTHORIZATION");
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/webhooks/")
  .get()
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

📘

Secret string

The request to retrieve all webhook subscriptions also returns the secret webhook string associated with each subscription in the response.

A successful response to an all-subscriptions request is show below.

[
  {
        "date_updated": "2020-11-17T11:14:23.553230",
        "date_created": "2020-11-17T11:14:23.553190",
        "webhook_id": "1e3ee35a-4ed2-4abd-bbd4-0e9d92b4038c",
        "callback_url": "https://hostname.com/webhook/one",
        "description": "KYC state changes.",
        "events": [
        "kyc.verification.success",
        "kyc.verification.failure",
        "kyc.verification.kba",
        "kyc.verification.error",
        "kyc.verification.timeout"
    ],
      "status": "enabled",
      "secret": "whsec_VYZThL3kK/3HbZzVyDeeXNQD598IXhWd"
  },
  {
      "date_updated": "2020-11-17T11:15:51.952724",
      "date_created": "2020-11-17T11:15:51.952714",
      "webhook_id": "651d2f40-b69e-4020-93eb-1e2a3dbdf02d",
      "callback_url": "https://hostname.com/webhook/two",
      "description": "Transactions and KYC state changes.",
      "events": [
        "kyc.verification.success",
        "kyc.verification.failure",
        "kyc.verification.kba",
        "kyc.verification.error",
        "kyc.verification.timeout",
        "transactions"
    ],
      "status": "enabled",
      "secret": "whsec_mbCTQL1qxVAAqnyKViPgJxaDcSvM4C+E"
  }
]

For a complete specification and interactive examples, see Retrieving all webhook subscriptions in the Bond API reference.

Updating a subscription

To update a subscription, use the PATCH /webhooks/{webhook_id} operation and provide the optional parameters as shown in the table below.

Parameter

Type

Description

callback_url

String

URL to which the event should be sent, for example, www.jamesbond.com.

description

String

Freeform description of the webhook's intended use.

events

Array of strings

One or more events to enable.
For a list of events, see Event types.

status

String

Set to enable or disable.

action

String

Set to add_events or remove_events.

An example of a request to update the webhook ID 40515057-7e8c-4ae1-b8d9-61ea3378cad5 to add the card.created event is shown below.

curl --request PATCH \
     --url https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5 \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '
{
     "events": [
          "card.created"
     ],
     "callback_url": "https://headquarters.com/webhook/route",
     "description": "KYC state changes update June 20 2021",
     "status": "enabled",
     "action": "add_events"
}
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Content-Type"] = 'application/json'
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'
request.body = "{\"events\":[\"card.created\"],\"callback_url\":\"https://headquarters.com/webhook/route\",\"description\":\"KYC state changes update June 20 2021\",\"status\":\"enabled\",\"action\":\"add_events\"}"

response = http.request(request)
puts response.read_body
const options = {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  },
  body: JSON.stringify({
    events: ['card.created'],
    callback_url: 'https://headquarters.com/webhook/route',
    description: 'KYC state changes update June 20 2021',
    status: 'enabled',
    action: 'add_events'
  })
};

fetch('https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = "https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5"

payload = {
    "events": ["card.created"],
    "callback_url": "https://headquarters.com/webhook/route",
    "description": "KYC state changes update June 20 2021",
    "status": "enabled",
    "action": "add_events"
}
headers = {
    "Content-Type": "application/json",
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

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

print(response.text)
var client = new RestClient("https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5");
var request = new RestRequest(Method.PATCH);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Identity", "YOUR-IDENTITY");
request.AddHeader("Authorization", "YOUR-AUTHORIZATION");
request.AddParameter("application/json", "{\"events\":[\"card.created\"],\"callback_url\":\"https://headquarters.com/webhook/route\",\"description\":\"KYC state changes update June 20 2021\",\"status\":\"enabled\",\"action\":\"add_events\"}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"events\":[\"card.created\"],\"callback_url\":\"https://headquarters.com/webhook/route\",\"description\":\"KYC state changes update June 20 2021\",\"status\":\"enabled\",\"action\":\"add_events\"}");
Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5")
  .patch(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

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

{
     "date_updated":"2021-06-27T14:38:55.198327",
     "date_created":"2021-06-01T07:22:18.153022",
     "webhook_id":"40515057-7e8c-4ae1-b8d9-61ea3378cad5",
     "callback_url":"https://headquarters.com/webhook/route",
     "description":"KYC state changes update June 20 2021",
          "events":[
               "card.created"
               "kyc.verification.kba"
     ],
     "status":"enabled",
     "secret":"whsec_SAPmRJ1RJxtD+lG5K6qm/Fkz/jHFsMz7"
}

For a complete specification and interactive examples, see Updating a webhook subscription in the Bond API reference.

Removing a subscription

To remove an event subscription, use the DELETE /webhooks/{webhook_id} operation with no further parameters.

An example of a request to remove the webhook subscription ID 40515057-7e8c-4ae1-b8d9-61ea3378cad5 is shown below.

curl --request DELETE \
     --url https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5 \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Identity: YOUR-IDENTITY'
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'

response = http.request(request)
puts response.read_body
const options = {
  method: 'DELETE',
  headers: {
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  }
};

fetch('https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = "https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5"

headers = {
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

response = requests.request("DELETE", url, headers=headers)

print(response.text)
var client = new RestClient("https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Identity", "YOUR-IDENTITY");
request.AddHeader("Authorization", "YOUR-AUTHORIZATION");
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5")
  .delete(null)
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

A successful response to a subscription removal request is show below.

{
  "deleted_at": "2020-11-17T12:39:24.546147",
  "date_created": "2020-11-17T12:39:12.846994",
  "webhook_id": "d2413481-6564-4977-a1cc-aefcba5f89b6",
  "callback_url": "https://hostname.com/webhook/route",
  "description": "KYC state changes.",
  "events": [
    "kyc.verification.success",
    "kyc.verification.failure",
    "kyc.verification.kba",
    "kyc.verification.error",
    "kyc.verification.timeout"
  ],
  "status": "disabled",
  "secret": "whsec_fmLMp39V+u4q8mQsizj+LTELLO5j5m0z"
}

For a complete specification and interactive examples, see Deleting a webhook subscription in the Bond API reference.


Did this page help you?