# Webhooks Stridge webhooks send real-time HTTP notifications when activity happens in your account — deposits, wallet assignments, transaction lifecycle updates, and balance changes — so you don't have to poll the API. ## How it works :::::steps ### An event is created Deposits, wallets, transactions, and balance changes generate events when account activity occurs. ### Stridge matches subscribers Active webhook subscribers for your tenant are filtered by event type. ### Stridge signs and sends the payload Each delivery is wrapped in a standard envelope, signed with **HMAC SHA-256**, and sent as an HTTP `POST` to your webhook URL. ### Stridge retries failed deliveries If your endpoint returns a non-2xx response or times out, Stridge retries with exponential backoff. ::::: :::info Deliveries follow the [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) with an envelope-based payload. ::: ## Event types | Event | Description | Trigger | | ------------------------- | ---------------------------- | ----------------------------------------------------- | | `deposit.new` | New deposit detected | A blockchain transaction is detected for your address | | `address.assigned` | Address assigned to an owner | A wallet address is assigned to a user or owner | | `transaction.broadcasted` | Transaction broadcasted | A transaction is submitted to the blockchain | | `transaction.confirmed` | Transaction confirmed | A transaction reaches required confirmations | | `transaction.failed` | Transaction failed | A transaction fails on-chain | | `balance.updated` | Balance updated | A wallet balance changes | ## Delivery format Every delivery uses the same envelope: ```json { "id": "7401d9c7-e29d-4374-8952-af40f05168b7", "version": "1", "type": "deposit.new", "time": "2026-02-08 09:46:54.699313", "payload": { "id": "550e8400-e29b-41d4-a716-446655440000", "network_symbol": "ethereum", "tx_hash": "0xabc123...", "amount": "100.50", "owner": "user@example.com" } } ``` | Field | Description | | --------- | -------------------------------------------- | | `id` | Unique event idempotency key | | `version` | Webhook format version, currently `1` | | `type` | Event type such as `deposit.new` | | `time` | Event timestamp | | `payload` | Event-specific payload data | ## Signature verification Each request includes three headers: | Header | Description | | ------------------- | -------------------------------------------- | | `webhook-id` | Unique event idempotency key | | `webhook-signature` | HMAC SHA-256 signature, hex-encoded | | `webhook-timestamp` | Unix timestamp when Stridge sent the request | The signature is computed as: ```text message = webhook-timestamp + "." + raw_request_body signature = HMAC-SHA256(signing_secret, message) ``` Verify it before trusting the body: :::code-group ```ts [Node.js] import { createHmac, timingSafeEqual } from 'node:crypto' export function verifyWebhookSignature( secret: string, body: string, timestamp: string, receivedSignature: string, ) { const message = `${timestamp}.${body}` const expected = createHmac('sha256', secret).update(message).digest('hex') return timingSafeEqual(Buffer.from(expected), Buffer.from(receivedSignature)) } ``` ```go [Go] func verifyWebhookSignature(secret, body, timestamp, receivedSignature string) bool { message := timestamp + "." + body h := hmac.New(sha256.New, []byte(secret)) h.Write([]byte(message)) expected := hex.EncodeToString(h.Sum(nil)) return hmac.Equal([]byte(expected), []byte(receivedSignature)) } ``` ```python [Python] import hmac, hashlib def verify_webhook_signature(secret, body, timestamp, received_signature): message = f"{timestamp}.{body}" expected = hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest() return hmac.compare_digest(expected, received_signature) ``` ::: :::warning Always verify the signature before processing the payload. Reject requests with old timestamps to reduce replay risk. ::: ## Retry behavior Stridge retries failed deliveries with exponential backoff — **up to 5 retries, 10 s initial delay, 10 min cap**. Any `2xx` response marks the delivery as successful. | Attempt | Delay | | ------- | ----------- | | 1 | Immediate | | 2 | 10 seconds | | 3 | 20 seconds | | 4 | 40 seconds | | 5 | 80 seconds | | 6 | 160 seconds | ## Consumer checklist * **Verify every signature** — check `webhook-signature` with the `webhook-timestamp`. * **Deduplicate by `webhook-id`** — retries will deliver the same event more than once. * **Respond fast** — return `2xx` immediately after enqueuing; process asynchronously. * **Expect duplicates** — idempotent handlers are required, not optional.