Developers

Server setup

Stridge webhooks send real-time HTTP POSTs to your server when activity happens in your account — deposits, transaction updates, UDA settlements — so you don't have to poll the API.

How it works

An event is created

Account activity — a confirmed deposit, a transaction update, a UDA settlement transition — produces an event.

Stridge matches subscribers

Active webhook subscribers for your tenant are filtered by event type.

Stridge signs and sends the delivery

The event is wrapped in the delivery envelope, signed with HMAC-SHA256, and POSTed to your subscriber URL.

Stridge retries failures

A non-2xx response or a transport error is retried with exponential backoff.

Delivery envelope

Every event — whatever its type — is wrapped in the same envelope before it is POSTed to your subscriber URL:

{
  "id": "7401d9c7-e29d-4374-8952-af40f05168b7",
  "version": "v1",
  "type": "deposit.confirmed",
  "time": "2026-04-24T06:55:59Z",
  "payload": {}
}
FieldTypeNotes
idstringEvent id — the idempotency key. Deduplicate on this.
versionstringEnvelope version, for example v1.
typestringThe event type — see Events list.
timestringEvent timestamp.
payloadobjectEvent-specific object — schemas in Events list.

HTTP headers

Every delivery carries three headers:

HeaderDescription
webhook-idEvent idempotency key — the same value as the envelope id.
webhook-timestampUnix timestamp (seconds) when the delivery was attempted.
webhook-signatureHMAC-SHA256(secret, "{timestamp}.{envelopeJSON}"), hex-encoded.

Use webhook-signature and webhook-timestamp to authenticate the request — see Verify signature for the algorithm and code samples.

Retries

A delivery that returns a non-2xx response or fails in transport is retried with exponential backoff, up to a configured maximum retry count. Any 2xx response marks the delivery as successful. Because every retry reuses the same envelope id, your handler must be idempotent — process each id once, even if it arrives more than once.

When the retry budget is exhausted, the delivery is marked permanently failed. See Get missed events for how to detect and reconcile those.

Handler checklist

  • Verify every signature — check webhook-signature over webhook-timestamp + the raw body, before parsing. See Verify signature.
  • Deduplicate by webhook-id — retries redeliver the same event with the same id.
  • Respond fast — return 2xx as soon as you have enqueued the event; process it asynchronously.
  • Switch on type — the envelope type tells you which payload schema to expect (Events list).
Was this page helpful?