Creating a webhook subscription

How to create a new 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.






URL to which the event should be sent.



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


array of strings

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



The version of the webhook event envelope to use.



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



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 \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR-AUTHORIZATION' \
     --header 'Content-Type: application/json' \
     --header 'Identity: YOUR-IDENTITY' \
     --data '
     "events": [
     "url": "",
     "description": "KYC state changes.",
     "version": "0.1",
     "status": "STATUS_ENABLED"
require 'uri'
require 'net/http'
require 'openssl'

url = URI("")

http =, url.port)
http.use_ssl = true

request =
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\":\"\",\"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: [
    url: '',
    description: 'KYC state changes.',
    version: '0.1',
    status: 'STATUS_ENABLED'

fetch('', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
import requests

url = ""

payload = {
    "events": ["card.created", "kyc.verification.success", "kyc.verification.failure", "kyc.verification.error", "kyc.verification.timeout"],
    "url": "",
    "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 =, json=payload, headers=headers)

var client = new RestClient("");
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\":\"\",\"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\":\"\",\"description\":\"KYC state changes.\",\"version\":\"0.1\",\"status\":\"STATUS_ENABLED\"}");
Request request = new Request.Builder()
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Identity", "YOUR-IDENTITY")
  .addHeader("Authorization", "YOUR-AUTHORIZATION")

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": "",
    "description": "KYC state changes.",
    "events": [
    "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.

Did this page help you?