Guides

Managing subscriptions

How do you manage your webhook subscriptions, for example by creating or updating a subscription.

Suggest Edits

Creating a subscription

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

ParameterTypeDescription
callback_url
required		stringURL to which the event should be sent.
descriptionstringFreeform description of the webhook's intended use, for example Jun 28 2021 KYC approved update.
events
required		array of stringsOne 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.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.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.

ParameterTypeDescription
webhook_id
required		stringThe ID of the webhook to update.
callback_urlstringURL to which the event should be sent, for example, www.jamesbond.com.
descriptionstringFreeform description of the webhook's intended use.
eventsarray of stringsOne or more events to enable.
For a list of events, see Event types.
statusstringSet to enable or disable.
actionstringSet 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"
     ],
     "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.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.

Updated almost 3 years ago

Next Steps