Skip to main content
Securitize notifies your partner account with webhooks: one POST per event to the HTTPS endpoint your Securitize contact registered for your account. The same endpoint receives the events of every API your account uses, so branch on eventType. Webhooks go to your systems, never to your investors. Every API sends the same body shape, the event envelope:
sourceEventId identifies the event, eventType says what happened and data carries it; each API adds its own fields, described on its page.

Headers

The headers follow the Standard Webhooks specification under the svix- prefix. The same headers under the webhook- prefix are planned; your code can read either name today, and the change will be announced in each API’s changelog before it happens.

Verify the signature

Every delivery is signed with your endpoint’s secret, a whsec_ string your Securitize contact handed you once. Verify before you parse anything else.
  • 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 two, one per secret, for 24 hours, 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 do all of this; they accept the svix- headers. By hand:
A delivery that fails verification: answer 401, log the svix-id, and do nothing with the body. The svix-id is only an input to the signature and a reference for support. Everything you key on, starting with sourceEventId, is in the body.

Acknowledge within 10 seconds

Any 2xx within 10 seconds acknowledges the delivery. Anything else, or no answer, is retried with exponential backoff for up to 72 hours; 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.

Deliveries are at least once and unordered

Retries repeat an event, and deliveries run in parallel, so a later event can arrive before an earlier one. Every handler needs:
  • Deduplication on sourceEventId. A retry carries the same id. Store the ids you have applied and skip a repeat.
  • A rule for late events. What decides which event is newer depends on the API; its page says which field to use.

Read back and resend

Every webhook sent to your endpoint stays readable for 90 days, of every API at once, and the deliveries that failed can be resent: GET /events, GET /events/{eventId} and POST /events/recover at https://partners-api.sandbox.securitize.io/webhooks/v1, with the bearer token of your client credentials. See Replay and recover.

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.
  • One endpoint for every Securitize webhook. The events of every API your account uses arrive at the same endpoint; branch on eventType. Your Securitize contact can limit the endpoint to some event types.
  • Monitoring. An endpoint that keeps failing is disabled after days of failures. Alert on your own 5xx rate.