Skip to main content

Understanding Real-Time Notifications with Securitize Webhooks

  • Updated

🎯 Purpose

Webhooks are a powerful way to receive real-time updates from Securitize without constantly polling our APIs. They allow your system to automatically react to events the moment they happen, making your workflows faster and more efficient.

Think of webhooks as "reverse APIs" — instead of you asking for updates, we send the updates directly to you!

🛠️ How Webhooks Work

When you subscribe to a webhook, Securitize will send an HTTP POST request to your application’s URL every time the event you selected occurs. This means:

  • You get instant updates.
  • You save resources because you don’t need to frequently pull data.

📚 Step-by-Step Guide to Webhooks

1️⃣ Define the Event You Want to Subscribe To

You can view all available events by calling:

curl --location --request GET 'https://public-api.{environment}.securitize.io/v1/webhooks/events' \
--header 'accept: application/json' \
--header 'Authorization: apiKey {apiKey}'

🔑 Parameters:

  • apiKey: Provided by Securitize.

📝 Example Response: 

[
  {
    "eventType": "health-check",
    "properties": ["externalId"]
  },
  {
    "eventType": "domain-investor-kyc-update",
    "properties": ["domainId", "externalId"]
  },
  {
    "eventType": "domain-investor-subscription-agreement-update",
    "properties": ["domainId", "tokenId", "roundId", "externalId"]
  }
]

✅ Current Supported Events:

  • health-check: For internal use only.
  • domain-investor-kyc-update: Notifies you when there’s a KYC update for an investor.
  • domain-investor-subscription-agreement-update: Notifies you when an investor completes a subscription agreement.

2️⃣ Subscribe to an Event

Use this POST request to create your webhook subscription:

curl --location --request POST 'https://public-api.{environment}.securitize.io/v1/webhooks/subscriptions' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: apiKey {apiKey}' \
--data-raw '{
  "domainId": "{domainId}",
  "eventType": "domain-investor-kyc-update",
  "payloadUrl": "{payloadUrl}",
  "isActive": true
}'

🔑 Parameters:

  • apiKey: Provided by Securitize.
  • domainId: Your issuer ID.
  • payloadUrl: The URL where you will receive the event notifications.
  • eventType: The event you’re subscribing to.

📝 Example Response: 

{
  "id": "6151edc0a46434001930z2e1",
  "domainId": "c2f82d16-178c-48ea-95c0-f72227c6fef4",
  "eventType": "domain-investor-kyc-update",
  "nonce": 0,
  "payloadUrl": "https://webhook.site/your-custom-url",
  "isActive": true
}

3️⃣ View Your Subscriptions

You can retrieve all your current subscriptions with:

curl --location --request GET 'https://public-api.{environment}.securitize.io/v1/webhooks/subscriptions?domainId={domainId}' \
--header 'accept: application/json' \
--header 'Authorization: apiKey {apiKey}'

Or get a specific subscription:

curl --location --request GET 'https://public-api.{environment}.securitize.io/v1/webhooks/subscriptions/{subscriptionId}' \
--header 'accept: application/json' \
--header 'Authorization: apiKey {apiKey}'

4️⃣ Update a Subscription

To update the URL or activation status of your subscription:

curl --location --request PATCH 'https://public-api.{environment}.securitize.io/v1/webhooks/subscriptions/{subscriptionId}' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: apiKey {apiKey}' \
--data-raw '{
  "payloadUrl": "{payloadUrl}",
  "isActive": {true|false}
}'

5️⃣ Delete a Subscription

If you no longer need a subscription, you can delete it:

curl --location --request DELETE 'https://public-api.{environment}.securitize.io/v1/webhooks/subscriptions/{subscriptionId}' \
--header 'accept: */*' \
--header 'Authorization: apiKey {apiKey}'

📥 Example Webhook Notification: domain-investor-kyc-update

When an investor’s KYC status is updated, you will receive a POST notification that looks like this:

{
  "domainId": "{domainId}",
  "externalId": "5298922124",
  "eventType": "domain-investor-kyc-update",
  "subscriptionId": "{subscriptionId}",
  "nonce": 1
}

What the Fields Mean:

  • domainId: Your issuer ID.
  • externalId: The ID of the investor whose KYC status changed.
  • eventType: The event that triggered the webhook.
  • subscriptionId: Your webhook subscription ID.
  • nonce: The number of times this event has been triggered.

📚 Additional Resources

You can find detailed API documentation and more examples here: Webhook API Documentation

 

Related articles