Skip to main content

Webhooks Client Service

NodeStack provides a first-class client.webhooks service in nodestack-client for managing outbound webhooks and verifying incoming signatures.


1. Create a Webhook Subscription​

const webhook = await client.webhooks.create({
name: 'Slack Notification Bridge',
url: 'https://api.myapp.com/webhooks/orders',
collection: 'orders',
action: 'create', // 'create' | 'update' | 'delete' | '*'
secret: 'whsec_9948a8cf38b1e42c',
enabled: true,
});

console.log('Registered webhook ID:', webhook.id);

2. Dispatch a Test Payload​

Trigger a mock webhook event to test external connectivity without mutating real database records:

const testResult = await client.webhooks.test(webhook.id, {
mockKey: 'mockValue',
});

console.log('Test delivery status code:', testResult.statusCode);
console.log('Delivery latency:', testResult.latencyMs, 'ms');

3. Inspect Delivery Logs​

Query the delivery attempts history:

const deliveries = await client.webhooks.getDeliveries({
webhookId: webhook.id,
status: 'failed',
});

console.log(`Found ${deliveries.items.length} failed delivery attempts`);

4. Retry a Failed Delivery​

Manually retry any failed delivery attempt:

if (deliveries.items.length > 0) {
const retryResult = await client.webhooks.retryDelivery(deliveries.items[0].id);
console.log('Retry result:', retryResult.status);
}

5. Verify Inbound Webhook Signatures​

In your downstream receiver service (e.g., Express, Next.js API route, Fastify), verify that payloads originated from NodeStack:

import NodeStackClient from 'nodestack-client';

const client = new NodeStackClient('http://localhost:8090');

export async function handleWebhook(req, res) {
const signature = req.headers['x-nodestack-signature'];
const rawBody = req.rawBody; // Make sure to use unparsed raw string body
const secret = process.env.WEBHOOK_SECRET;

const isValid = client.webhooks.verifySignature(rawBody, signature, secret);

if (!isValid) {
return res.status(401).send('Signature verification failed');
}

// Signature valid! Process payload safely.
const payload = JSON.parse(rawBody);
console.log('Verified event:', payload.event, payload.record);
res.status(200).send({ received: true });
}