Receive webhooks

Securitize sends one POST to your webhook endpoint for every step of your activity: cash movements, token issuances, transactions, redemptions and payouts. Your Securitize contact registers the endpoint’s URL for your account, chooses with you which event types it receives, and hands you its signing secret, a whsec_ string, once.

POST https://your.endpoint.invalid/securitize/subscriptions
content-type: application/json
svix-id: msg_2ZxKa1bQ7mN3pR5tV7xZ9bD1fH
svix-timestamp: 1778171069
svix-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{"eventType":"investor.deposit.processed","eventId":"investor.deposit.processed-99001","timestamp":"2026-05-05T10:00:03.118Z","data":{"id":"99001","tokenId":"d1dbb6b6-3bda-48f2-b86e-c87610db1ae1","currencyId":1,"amount":"500000000","decimals":2,"direction":"deposit","uetr":"f3a1b2c3-6d4e-4f5a-9b8c-1d2e3f4a5b6c","date":"2026-05-05T10:00:00.000Z"}}

The body is the event envelope: eventType says what happened, eventId identifies the event, data carries it.

Headers

Header	What it is
`svix-id`	The message id of the delivery, `msg_…`, the same on every retry of it. It is not the event id: deduplicate on `eventId` in the body
`svix-timestamp`	When the delivery was signed, Unix seconds
`svix-signature`	One or more signatures, space-separated, each `v1,` followed by base64

The headers follow the Standard Webhooks specification under the svix- prefix. Read them case-insensitively.

Verify the signature

Every delivery is signed with your endpoint’s secret. Verify before you parse anything else.

signature = base64( HMAC-SHA256( secret, svix-id + "." + svix-timestamp + "." + raw body ) )

Sign the raw bytes of the body, exactly as received, before any JSON parsing or re-serialisation.
Compare in constant time against each signature in svix-signature: during a secret rotation the header carries one per secret, and any one matching is enough.
Reject a timestamp more than 5 minutes from your clock, to stop a captured delivery being replayed later.
The secret is base64 after the whsec_ prefix; decode it before using it as the HMAC key.

The Standard Webhooks libraries and the svix libraries do all of this. By hand:

import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRET = Buffer.from(process.env.IA_WEBHOOK_SECRET.replace(/^whsec_/, ''), 'base64');
const TOLERANCE_SECONDS = 5 * 60;

// `headers` with lowercase names; `rawBody` is the request body as bytes, read before any JSON middleware runs.
export function verify(headers, rawBody) {
  const id = headers['svix-id'];
  const timestamp = headers['svix-timestamp'];
  const signatures = headers['svix-signature'];
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const expected = createHmac('sha256', SECRET)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest();
  return signatures.split(' ').some((entry) => {
    const [version, value] = entry.split(',');
    if (version !== 'v1' || !value) return false;
    const given = Buffer.from(value, 'base64');
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

import base64, hmac, hashlib, os, time

SECRET = base64.b64decode(os.environ["IA_WEBHOOK_SECRET"].removeprefix("whsec_"))
TOLERANCE_SECONDS = 5 * 60


def verify(headers: dict, raw_body: bytes) -> bool:
    """`raw_body` is the request body as received, before any JSON parsing."""
    h = {k.lower(): v for k, v in headers.items()}
    msg_id, timestamp, signatures = h.get("svix-id"), h.get("svix-timestamp"), h.get("svix-signature")
    if not (msg_id and timestamp and signatures):
        return False
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(SECRET, f"{msg_id}.{timestamp}.".encode() + raw_body, hashlib.sha256).digest()
    for entry in signatures.split(" "):
        version, _, value = entry.partition(",")
        if version == "v1" and value and hmac.compare_digest(base64.b64decode(value), expected):
            return True
    return False

A delivery that fails verification: answer 401, log the svix-id, and do nothing with the body.

Acknowledge quickly

Any 2xx within 15 seconds acknowledges the delivery. Anything else, or no answer, is retried with increasing delays, from seconds to hours, for about a day; after that the delivery is marked failed. Acknowledge as soon as the event is durably stored, and do the work afterwards. A handler that calls your own systems before answering is the usual cause of timeouts, and every timeout is a retry you then have to deduplicate.

Apply it exactly once

Delivery is at least once and can be out of order: retries repeat an event, and the steps of one subscription or redemption are recorded by different parts of Securitize, so a later step can arrive first.

Rule	On what	Why
Deduplicate on `eventId`	Every event	A retry, and a resend, carry the same `eventId`. Store the ids you have applied and skip a repeat
Upsert by id	`data.id`, `tokenIssuanceId`, `txHash`	Each step names the object it is about. Create the record the first time any step mentions it, and fill it in as the other steps arrive
Order by the business step, not by arrival	`eventType`, `status`	`investor.payout.completed` after `investor.payout.initiated` is the normal course, but both can arrive in either order. Never move a record back to an earlier step

timestamp in the envelope is when Securitize sent the event; the time the step happened is in data (date, sourceTransaction.date). A handler that follows the three rules:

export async function handle(event) {
  // 1. Deduplicate.
  if (await store.hasEvent(event.eventId)) return;

  // 2. Upsert by id, 3. never move a record back.
  switch (event.eventType) {
    case 'investor.deposit.processed':
      await store.upsertDeposit(event.data.id, event.data);
      break;
    case 'investor.minting.completed':
      await store.upsertIssuance(event.data.id, event.data);
      for (const d of event.data.depositMovements) await store.linkDeposit(d.id, event.data.id);
      break;
    case 'investor.transaction.processed':
      await store.upsertTransaction(event.data.id, event.data);
      if (event.data.tokenIssuanceId) await store.linkTransaction(event.data.tokenIssuanceId, event.data.id);
      break;
    case 'investor.redemption.pending':
    case 'investor.redemption.confirmed':
    case 'investor.payout.initiated':
    case 'investor.payout.completed':
      await store.advanceRedemption(event.data.id, event.eventType, event.data);
      break;
    default:
      // A type you do not know yet: store it and move on.
      await store.keepUnknown(event);
  }

  await store.markEvent(event.eventId);
}

Find what you missed

Every webhook sent to you stays readable: GET /webhook-events lists them newest first, with the body exactly as delivered, and GET /webhook-events/{eventId} returns one by its eventId or its svix-id. After an outage, page the list back to the start of the outage and apply what you do not have; your deduplication on eventId makes it safe. For anything older, or to confirm a final state, read the deposits and transactions themselves.

Your endpoint

HTTPS, publicly reachable, with a certificate a public CA issued.
Idempotent: a retry repeats a delivery, so applying the same event twice must change nothing.
One endpoint per environment: sandbox and production have different secrets and different events.
Monitoring. An endpoint that keeps failing can be disabled. Alert on your own 5xx rate, and tell your Securitize contact when you change the URL.

Get started

Guides

Concepts

Help

API reference

Headers

Verify the signature

Acknowledge quickly

Apply it exactly once

Find what you missed

Your endpoint