Webhook
Fan-out event distribution with HMAC signing and glob matching
Webhook
OqronKit's Webhook module handles fan-out event distribution with HMAC signing, glob pattern matching, circuit breakers, and a dead letter queue.
Basic Usage
import { webhook } from 'oqronkit'
export const platformWebhooks = webhook({
name: 'platform-events',
concurrency: 10,
retries: {
max: 3,
strategy: 'exponential',
baseDelay: 2000,
},
security() {
return {
signingSecret: process.env.WEBHOOK_SECRET!,
}
},
async endpoints() {
return [
{
name: 'AcmeCorp Integration',
url: 'https://api.acme.com/v1/webhooks/receive',
events: ['order.**', 'user.signup'], // Glob matching
security: {
signingAlgorithm: 'sha256',
signingSecret: process.env.ACME_SECRET!,
signingHeader: 'x-acme-signature',
},
},
{
name: 'Internal Analytics',
url: 'https://data.internal.svc/ingest',
events: ['user.*.activated', 'system.health'],
},
]
},
})Fire Events
// Matches AcmeCorp (order.**) — ignored by Internal Analytics
platformWebhooks.fire('order.payment.completed', {
orderId: 'ord_123',
amount: 450.0,
currency: 'USD',
})
// Matches AcmeCorp (user.signup)
platformWebhooks.fire('user.signup', {
userId: 'usr_abc',
email: 'newuser@example.com',
})
// Matches Internal Analytics (user.*.activated)
platformWebhooks.fire('user.onboarding.activated', {
userId: 'usr_abc',
timestamp: Date.now(),
})Dynamic CRUD
import { createWebhook, updateWebhook, deleteWebhook, pauseWebhook, resumeWebhook, resendWebhook } from 'oqronkit'
// Create at runtime
await createWebhook({ /* ... */ })
// Pause/Resume
await pauseWebhook('webhook-id')
await resumeWebhook('webhook-id')
// Resend a failed delivery
await resendWebhook('delivery-id')v0.0.2 improvements:
- Abort signal support — Cancelling an active webhook job via
cancelJob()now immediately aborts the in-flight HTTP request, rather than waiting for the full timeout.- Resend clears delay —
resendWebhook()now clearsrunAtandopts.delayon the cloned job, ensuring immediate re-dispatch instead of inheriting the original schedule.
Signature Verification
import { verifyWebhookSignature, signWebhookPayload } from 'oqronkit'
// Verify incoming webhook (consumer side)
const isValid = verifyWebhookSignature(payload, signature, secret, 'sha256')
// Sign outgoing payload (producer side)
const sig = signWebhookPayload(payload, secret, 'sha256')Circuit Breaker
import { createCircuitBreaker } from 'oqronkit'
const breaker = createCircuitBreaker({
failureThreshold: 5,
resetTimeout: 30_000,
})Next Steps
- Rate Limiter — Protect webhook dispatch with rate limits
- Task Queue — Use queues for reliable background processing