Developer Documentation & API Reference
Complete technical specification for high-throughput zero-block webhook ingestion, HMAC validation, and programmatic Dead-Letter Queue replay.
1. Overview & Ingress Resilience
Kustomcode Relay acts as an ultra-low latency, zero-block webhook reverse proxy. Designed for high-volume Stripe, Shopify, and e-commerce webhooks, it buffers incoming byte payloads directly into a private BullMQ/Redis pipeline and returns an immediate 202 Accepted acknowledgement in sub-3ms.
2. Ingestion Protocol
Replace your webhook destination endpoint in your Stripe or Shopify dashboard with your Kustomcode Ingress URL:
curl -X POST https://relay-production-54ca.up.railway.app/v1/in/ep_live_99f2b8a7c1 \
-H "Content-Type: application/json" \
-H "X-Client-Signature: 8f2c6e147b..." \
-d '{
"event": "checkout.session.completed",
"amount": 4900,
"currency": "usd",
"customer": "vip@acme-enterprise.com"
}'Expected Response (`202 Accepted`)
3. Downstream Forwarding & Headers
When Relay delivers the buffered payload to your downstream target URL, all original sender headers are preserved intact. Relay also attaches metadata headers to facilitate idempotency and tracing:
| Header | Example Value | Description |
|---|---|---|
| X-Relay-Delivery-Id | del_89f02b11a | Unique immutable ID for idempotency key indexing |
| X-Relay-Attempt | 1 | Current retry delivery attempt number (1 through 10) |
| X-Relay-Timestamp | 1756560250119 | Original millisecond timestamp when the payload hit the proxy |
4. HMAC Signature Verification Guide
Verify authentic webhooks on your downstream server using timing-safe cryptographic comparisons.
Shopify Signature Verification (`X-Shopify-Hmac-Sha256`)
Shopify calculates a Base64-encoded HMAC-SHA256 signature using your store's Webhook Shared Secret.
import crypto from 'crypto';
export function verifyShopifyWebhook(
rawBody: string | Buffer,
shopifyHeader: string,
secret: string
): boolean {
const hash = crypto
.createHmac('sha256', secret)
.update(rawBody)
.digest('base64');
// Use timingSafeEqual to protect against timing attacks
const calculatedBuf = Buffer.from(hash, 'utf8');
const receivedBuf = Buffer.from(shopifyHeader, 'utf8');
if (calculatedBuf.length !== receivedBuf.length) {
return false;
}
return crypto.timingSafeEqual(calculatedBuf, receivedBuf);
}Stripe Signature Verification (`Stripe-Signature`)
Stripe sends a Unix timestamp and hex-encoded HMAC-SHA256 signature to protect against replay attacks.
import crypto from 'crypto';
export function verifyStripeWebhook(
rawBody: string,
stripeSignatureHeader: string,
secret: string,
toleranceSeconds = 300
): boolean {
// Header format: t=1756560000,v1=9e8bf69e7...
const items = stripeSignatureHeader.split(',');
const timestamp = items.find((i) => i.startsWith('t='))?.slice(2);
const signature = items.find((i) => i.startsWith('v1='))?.slice(3);
if (!timestamp || !signature) return false;
// Prevent replay attacks
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > toleranceSeconds) {
return false;
}
const payloadToSign = `${timestamp}.${rawBody}`;
const computedHash = crypto
.createHmac('sha256', secret)
.update(payloadToSign, 'utf8')
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(computedHash, 'hex'),
Buffer.from(signature, 'hex')
);
}5. Programmatic Dead-Letter Queue (DLQ) API
Audit, inspect, and replay failed webhooks programmatically using the Kustomcode Relay REST API.
Returns failed webhook payloads with full error traces and attempt histories.
Pushes the dead event back into the BullMQ active queue for immediate dispatch.
# Replay a single failed dead-letter webhook event
curl -X POST https://relay-production-54ca.up.railway.app/v1/events/evt_dead_9921b7/replay \
-H "Authorization: Bearer kustom_sec_live_9941a8" \
-H "Content-Type: application/json"
# Response:
# {"replayed": true, "eventId": "evt_dead_9921b7", "status": "PENDING"}6. Interactive Ingress Sandbox
Fire test payloads and watch the sub-3ms ingestion handshake and delivery lifecycle live:
Interactive Ingress GatewayProduction API
Dispatch webhook events to benchmark zero-block 202 ingress & cryptographic audit capture
Ready for Ingestion
Click Dispatch Webhook to trigger live pipeline