@prudra/webhooks

Prudra webhook SDK — two things: HMAC signature verification for incoming webhooks, and a programmatic client for managing webhook subscriptions.

Installation

npm install @prudra/webhooks

1. Verifying Incoming Webhooks

The most important feature. Use verifyWebhook() to validate that incoming payloads are authentic and haven't been tampered with.

Use express.raw(), not express.json(), on the webhook route. JSON parsing before verification will break signature checking because the raw bytes must match the HMAC.

import express from 'express';
import { verifyWebhook } from '@prudra/webhooks';

const app = express();

app.post(
  '/prudra/events',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const result = verifyWebhook({
      payload:   req.body,
      signature: req.headers['x-prudra-signature'] as string,
      timestamp: req.headers['x-prudra-timestamp'] as string,
      secret:    process.env.PRUDRA_WEBHOOK_SECRET!,
    });

    if (!result.valid) {
      console.error('Webhook verification failed:', result.error);
      return res.status(401).end();
    }

    const event = result.event!;
    console.log(`Received ${event.type}:`, event.data);

    switch (event.type) {
      case 'vault.sealed':
        // Handle sealed vault
        break;
      case 'payment.received':
        // Handle payment
        break;
    }

    res.status(200).end();
  },
);

verifyWebhook() never throws. All errors return { valid: false, error: '...' }.

2. Registering Webhooks Programmatically

Requires initialise() from @prudra/core.

import { initialise } from '@prudra/core';
import { registerWebhook, listWebhooks, updateWebhook, deleteWebhook } from '@prudra/webhooks';

initialise({ apiKey: process.env.PRUDRA_API_KEY! });

// Register
const webhook = await registerWebhook({
  url: 'https://yourapp.com/prudra/events',
  events: ['vault.sealed', 'payment.received'],
});

// List all
const webhooks = await listWebhooks();

// Update
await updateWebhook(webhook.id, {
  events: ['*'], // Subscribe to all events
});

// Delete
await deleteWebhook(webhook.id);

3. Inspecting Deliveries

Debug failed webhook deliveries and replay them after fixing your endpoint.

import { listDeliveries, replayDelivery } from '@prudra/webhooks';

// List recent failures
const result = await listDeliveries(webhookId, {
  status: 'failed',
  limit: 10,
});

for (const delivery of result.data) {
  console.log(`${delivery.eventType} — ${delivery.attempts} attempts`);
}

// Replay a failed delivery
await replayDelivery(webhookId, deliveryId);

4. Available Event Types

| Event | Description | |-------|-------------| | vault.created | A new vault was created | | vault.file.added | A file was uploaded to a vault | | vault.document.added | A document was added to a vault | | vault.event | A custom event was emitted via vault.emit() | | vault.sealed | A vault was sealed (read-only) | | vault.expiring | A vault is approaching its TTL expiry | | vault.expired | A vault has expired | | payment.received | A payment was verified and recorded |

Use ['*'] when registering to subscribe to all event types.

Documentation

Full documentation: docs.prudra.dev/docs/webhooks