Webhooks
Receive signed, normalized event deliveries and verify them.
Stacklink delivers every matched trigger event to one project webhook endpoint, as a signed v1 envelope. Configure the endpoint once, then verify each delivery.
1 endpointFor everythingone URL, one envelope shape
HMAC-SHA256Signedconstant-time verify helper in the SDK
RetriesWith dead-letterfailed deliveries can be redriven
Configure your endpoint
curl -X PUT http://localhost:4100/v1/webhook \
-H "authorization: Bearer $STACKLINK_API_KEY" \
-H "content-type: application/json" \
-d '{"callbackUrl":"https://app.example.com/stacklink/webhook","status":"active","eventTypes":["stacklink.trigger.event"]}'The envelope
{
"version": "v1",
"id": "evt_...",
"type": "stacklink.trigger.event",
"metadata": {
"trigger_id": "...", "connected_account_id": "...",
"tenant_id": "biz_123", "provider_key": "zoho_books"
},
"data": { /* normalized provider payload */ },
"timestamp": "2026-05-08T05:30:00+05:30"
}Verify the signature
Always verify before trusting a delivery. The SDK ships a constant-time helper:
import { verifyWebhookSignature } from 'stacklink/sdk';
const ok = await verifyWebhookSignature({
id: req.headers['webhook-id'],
timestamp: req.headers['webhook-timestamp'],
signature: req.headers['webhook-signature'],
body: rawBody,
secret: process.env.STACKLINK_WEBHOOK_SECRET!,
});
if (!ok) return res.status(400).end();Reserved event types & retries
stacklink.trigger.event, stacklink.connected_account.expired, and stacklink.trigger.disabled.
Failed deliveries retry with backoff and land in a dead-letter queue you can redrive.