Creating a webhook subscription

Creating a subscription

To set up an active event subscription, pass a list containing one or more events to the webhooks API for which you want to be notified.

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

Parameter	Type	Description
`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.
`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`.

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

The following is an example of a request to create webhook subscriptions.

curl --request POST \
     --url https://sandbox.bond.tech/api/v0.1/webhooks \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '
{
     "events": [
          "card.created",
          "kyc.verification.success",
          "kyc.verification.failure",
          "kyc.verification.error",
          "kyc.verification.timeout"
     ],
     "url": "https://hostname.com/webhook/route",
     "description": "KYC state changes.",
     "version": "0.1",
     "status": "STATUS_ENABLED"
}
'

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::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request["Identity"] = 'YOUR-IDENTITY'
request["Authorization"] = 'YOUR-AUTHORIZATION'
request.body = "{\"events\":[\"card.created\",\"kyc.verification.success\",\"kyc.verification.failure\",\"kyc.verification.error\",\"kyc.verification.timeout\"],\"url\":\"https://hostname.com/webhook/route\",\"description\":\"KYC state changes.\",\"version\":\"0.1\",\"status\":\"STATUS_ENABLED\"}"

response = http.request(request)
puts response.read_body

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Identity: 'YOUR-IDENTITY',
    Authorization: 'YOUR-AUTHORIZATION'
  },
  body: JSON.stringify({
    events: [
      'card.created',
      'kyc.verification.success',
      'kyc.verification.failure',
      'kyc.verification.error',
      'kyc.verification.timeout'
    ],
    url: 'https://hostname.com/webhook/route',
    description: 'KYC state changes.',
    version: '0.1',
    status: 'STATUS_ENABLED'
  })
};

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"

payload = {
    "events": ["card.created", "kyc.verification.success", "kyc.verification.failure", "kyc.verification.error", "kyc.verification.timeout"],
    "url": "https://hostname.com/webhook/route",
    "description": "KYC state changes.",
    "version": "0.1",
    "status": "STATUS_ENABLED"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Identity": "YOUR-IDENTITY",
    "Authorization": "YOUR-AUTHORIZATION"
}

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

print(response.text)

var client = new RestClient("https://sandbox.bond.tech/api/v0.1/webhooks");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "application/json");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Identity", "YOUR-IDENTITY");
request.AddHeader("Authorization", "YOUR-AUTHORIZATION");
request.AddParameter("application/json", "{\"events\":[\"card.created\",\"kyc.verification.success\",\"kyc.verification.failure\",\"kyc.verification.error\",\"kyc.verification.timeout\"],\"url\":\"https://hostname.com/webhook/route\",\"description\":\"KYC state changes.\",\"version\":\"0.1\",\"status\":\"STATUS_ENABLED\"}", 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\",\"kyc.verification.success\",\"kyc.verification.failure\",\"kyc.verification.error\",\"kyc.verification.timeout\"],\"url\":\"https://hostname.com/webhook/route\",\"description\":\"KYC state changes.\",\"version\":\"0.1\",\"status\":\"STATUS_ENABLED\"}");
Request request = new Request.Builder()
  .url("https://sandbox.bond.tech/api/v0.1/webhooks")
  .post(body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")
  .build();

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

The following is an example of a response to a successful request to create webhook subscriptions.

{
  "webhook_subscription": {
    "id": "487a7f29-7b80-467d-b20d-7b60c3a14cf0",
    "url": "https://hostname.com/webhook/route",
    "description": "KYC state changes.",
    "events": [
      "card.created",
          "kyc.verification.success",
          "kyc.verification.failure",
          "kyc.verification.error",
          "kyc.verification.timeout"
    ],
    "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"
  }
}

The response contains a unique webhook "secret" string, (in this example, whsec_ira5jceuzhxxBxoWckAU0hLFQe79bSMZ), 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.

For a complete specification and interactive examples, see Creating a webhook subscription.

Creating a subscription

📘Note

📘
Note