Guides

Managing subscriptions

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

Suggest Edits

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.

ParameterTypeDescription
urlstringURL to which the event should be sent, for example, www.bondjames.com.
descriptionstringFreeform description of the webhook's intended use.
eventsarray of stringsOne or more events to update.
For a list of events, see Event types.
versionstringThe version of the webhook event envelope to use.
statusstringThe 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.

Updated about 2 years ago

Next Steps