Webhooks Overview

​

Why webhooks

• Freshness. A webhook delivers within seconds of the source event. A polled sync runs on whatever interval you configure — typically minutes or hours.
• Cost. Webhook deliveries do not count against your hourly rate limit. A poll that scans for recent changes does — even when nothing has changed.
• Completeness. Webhooks fire for events generated by any source — your own integration, other integrations, manual entry by a Virtuous user, the nightly Transaction batch. A poll only sees changes that landed before your last query timestamp.

​

How the flow works

1. Subscribe. Your integration calls POST /api/Webhook to register a payload URL and select which events you want delivered. Virtuous returns the subscription details, including the secret used for signature verification.
2. Receive. When a subscribed event occurs in the nonprofit’s Virtuous organization, Virtuous sends an HTTP POST to your payloadUrl with the event payload.
3. Verify and process. Your endpoint verifies the request signature (proving the request came from Virtuous and was not tampered with), then processes the event.
4. Acknowledge. Your endpoint returns a 2xx HTTP status to confirm delivery. Non-2xx responses trigger retries — see Retry Behavior.

​

Subscribing to webhooks

curl -X POST https://api.virtuoussoftware.com/api/Webhook \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payloadUrl": "https://your-integration.example.com/virtuous/webhook",
    "secret": "your-randomly-generated-secret",
    "contactCreate": true,
    "contactUpdate": true,
    "giftCreate": true,
    "giftUpdate": true,
    "giftDelete": false,
    "projectCreate": false,
    "projectUpdate": false,
    "projectDelete": false,
    "formSubmission": false,
    "contactNoteCreate": false,
    "contactNoteUpdate": false,
    "contactNoteDelete": false,
    "eventCreate": false,
    "eventUpdate": false,
    "eventDelete": false,
    "active": true
  }'

const response = await fetch(
  'https://api.virtuoussoftware.com/api/Webhook',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.VIRTUOUS_API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      payloadUrl: 'https://your-integration.example.com/virtuous/webhook',
      secret: process.env.VIRTUOUS_WEBHOOK_SECRET,
      contactCreate: true,
      contactUpdate: true,
      giftCreate: true,
      giftUpdate: true,
      active: true,
    }),
  }
);

const subscription = await response.json();
console.log('Webhook subscription created:', subscription.id);

{
  "id": 1042,
  "payloadUrl": "https://your-integration.example.com/virtuous/webhook",
  "secret": "your-randomly-generated-secret",
  "contactCreate": true,
  "contactUpdate": true,
  "giftCreate": true,
  "giftUpdate": true,
  "giftDelete": false,
  "projectCreate": false,
  "projectUpdate": false,
  "projectDelete": false,
  "formSubmission": false,
  "contactNoteCreate": false,
  "contactNoteUpdate": false,
  "contactNoteDelete": false,
  "eventCreate": false,
  "eventUpdate": false,
  "eventDelete": false,
  "active": true
}

​

The subscription fields

​

Generating the secret

import crypto from 'crypto';

// Generate a 32-byte random string, base64-encoded
const secret = crypto.randomBytes(32).toString('base64');

​

Managing webhook subscriptions

​

Updating the event selections

curl -X PUT https://api.virtuoussoftware.com/api/Webhook/1042 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payloadUrl": "https://your-integration.example.com/virtuous/webhook",
    "secret": "your-randomly-generated-secret",
    "contactCreate": true,
    "contactUpdate": true,
    "giftCreate": true,
    "giftUpdate": true,
    "giftDelete": true,
    "projectUpdate": true,
    "active": true
  }'

​

Rotating the secret

​

Endpoint requirements

​

The receiver pattern

import express from 'express';
import { verifyVirtuousSignature } from './signature-verification.js';

const app = express();

// Capture the raw body before JSON parsing — needed for signature verification
app.post(
  '/virtuous/webhook',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    // 1. Verify the signature — see /crm/webhooks/signature-verification
    const valid = verifyVirtuousSignature(req.body, req.headers, process.env.VIRTUOUS_WEBHOOK_SECRET);
    if (!valid) {
      return res.status(401).send('Invalid signature');
    }

    // 2. Parse the event payload
    const event = JSON.parse(req.body.toString('utf8'));

    // 3. Acknowledge immediately — defer processing
    res.status(200).send('OK');

    // 4. Process asynchronously (queue, background job, etc.)
    await processVirtuousEvent(event);
  }
);

• Capture the raw body. Signature verification runs over the exact bytes Virtuous sent. JSON-parsing-then-re-serializing changes whitespace and ordering, which breaks the signature.
• Acknowledge before processing. Return 2xx as soon as you have verified and stored the event. Heavy processing in the request handler increases the risk of timeout-triggered retries.
• Queue the work. A robust integration pushes the event onto a background queue (SQS, Cloud Tasks, Redis Stream, etc.) and processes asynchronously. This isolates the webhook endpoint’s latency from the cost of downstream processing.

​

Where to go next