Managing subscriptions

How to manage your webhook subscriptions, for example, creating or updating a subscription.

Use the operations shown below to manage webhook subscriptions:

📘

Note

You can also use wildcards when managing webhooks. For example, to refer to all card webhooks, use card*.

Retrieving all subscriptions

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

The following is an example of a request to retrieve a list of all subscriptions.

curl --request GET \
     --url https://sandbox.bond.tech/api/v0.1/webhooks \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Identity: YOUR-IDENTITY'
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0.1/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.1/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.1/webhooks"

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

response = requests.get(url, headers=headers)

print(response.text)
var client = new RestClient("https://sandbox.bond.tech/api/v0.1/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.1/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.

The following is a response to a successful all-subscriptions request.

{
  "webhook_subscriptions": [
    {
      "id": "487a7f29-7b80-467d-b20d-7b60c3a14cf0",
      "url": "https://hostname.com/webhook/route",
      "description": "Account history is ready.",
      "events": [
        "account.history.ready"
      ],
      "version": "0.1",
      "secret": "string",
      "status": "enabled",
      "created_time": "2022-06-09T18:23:37.585421Z",
      "updated_time": "2022-06-09T18:23:37.585421Z"
    }
  ]
}

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 body parameters as shown in the table below.

📘

Note

When you update a webhook_id, the list of webhook events that you supply in the API call replaces the existing list associated with that webhook_id.

Parameter

Type

Description

url

string

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

description

string

Freeform description of the webhook's intended use.

events

array of strings

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

version

string

The version of the webhook event envelope to use.

status

string

The status to set of the webhook, either STATUS_ENABLED or STATUS_DISABLED.

The following is an example of a request to update the webhook ID 40515057-7e8c-4ae1-b8d9-61ea3378cad5 to subscribe to only the account.history.ready event.

curl --request PATCH \
     --url https://sandbox.bond.tech/api/v0.1/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5 \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '
{
     "events": [
          "account.history.ready"
     ]
}
'
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox.bond.tech/api/v0.1/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\":[\"account.history.ready\"]}"

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: ['account.history.ready']})
};

fetch('https://sandbox.bond.tech/api/v0.1/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.1/webhooks/40515057-7e8c-4ae1-b8d9-61ea3378cad5"

payload = {"events": ["account.history.ready"]}
headers = {
    "Content-Type": "application/json",
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)
var client = new RestClient("https://sandbox.bond.tech/api/v0.1/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\":[\"account.history.ready\"]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"events\":[\"account.history.ready\"]}");
Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0.1/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();

The following is a response to a successful subscription update request.

{
  "webhook_subscription": {
    "id": "487a7f29-7b80-467d-b20d-7b60c3a14cf0",
    "url": "https://hostname.com/webhook/route",
    "description": "Account history is ready.",
    "events": [
      "account.history.ready"
    ],
    "version": "0.1",
    "secret": "whsec_ira5jceuzhxxBxoWckAU0hLFQe79bSMZ",
    "status": "STATUS_ENABLED",
    "created_time": "2022-06-09T18:23:37.585421Z",
    "updated_time": "2022-06-09T18:23:37.585421Z"
  }
}

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.

The following is an example of a request to remove the webhook subscription ID 40515057-7e8c-4ae1-b8d9-61ea3378cad5.

curl --request DELETE \
     --url https://sandbox.bond.tech/api/v0.1/webhooks/webhook_id \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Identity: YOUR-IDENTITY'
require 'uri'
require 'net/http'
require 'openssl'

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

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.1/webhooks/webhook_id', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

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

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

response = requests.delete(url, headers=headers)

print(response.text)
var client = new RestClient("https://sandbox.bond.tech/api/v0.1/webhooks/webhook_id");
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.1/webhooks/webhook_id")
  .delete(null)
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

The following is an example of a successful response to a subscription removal request.

{
  "webhook_subscription": {
    "id": "487a7f29-7b80-467d-b20d-7b60c3a14cf0",
    "url": "https://hostname.com/webhook/route",
    "description": "Account history is ready.",
    "events": [
      "account.history.ready"
    ],
    "version": "0.1",
    "secret": "whsec_ira5jceuzhxxBxoWckAU0hLFQe79bSMZ",
    "status": "STATUS_ENABLED",
    "created_time": "2022-06-09T18:23:37.585421Z",
    "updated_time": "2022-06-09T18:23:37.585421Z"
  }
}

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


Did this page help you?