Quickstart

Get your first monitor running in under 2 minutes.

1. Get an API key

export VERID_API_KEY="vrd_your_key_here"

API keys start with the prefix vrd_. Treat them like passwords — they grant full access to your account.

2. Create a monitor

Let's monitor the GitHub React repository for new releases:

curl -X POST https://api.verid.dev/v1/monitors \
  -H "Authorization: Bearer $VERID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "React New Releases",
    "url": "https://api.github.com/repos/facebook/react/releases/latest",
    "schedule_interval_seconds": 3600,
    "extract_config": {
      "method": "json_path",
      "fields": {
        "tag_name": "$.tag_name",
        "name": "$.name",
        "published_at": "$.published_at"
      }
    },
    "diff_predicate": {
      "type": "field_changes",
      "field": "tag_name"
    },
    "deliveries": [
      {
        "type": "webhook",
        "url": "https://your-app.com/webhooks/verid"
      }
    ]
  }'

3. Receive webhook notifications

When React publishes a new release, you'll receive a POST request:

{
  "id": "del_01H...",
  "version": "2026-05-01",
  "monitor_id": "uuid",
  "run_id": "uuid",
  "fired_at": "2026-05-08T12:00:00Z",
  "diff": {
    "fields_changed": ["tag_name"],
    "before": { "tag_name": "v18.2.0" },
    "after":  { "tag_name": "v18.3.0" }
  },
  "monitor": {
    "url":  "https://api.github.com/repos/facebook/react/releases/latest",
    "name": "React New Releases"
  }
}

4. Verify the signature

All webhooks are signed. Verify the Verid-Signature header before processing:

import { createHmac, timingSafeEqual } from 'crypto';
 
function verifySignature(header: string, rawBody: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const ts = parseInt(parts['t'] ?? '0', 10);
  const sig = parts['v1'];
  if (!ts || !sig) return false;
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false; // 5 min drift
 
  const expected = createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(sig, 'hex'));
}
 
app.post('/webhooks/verid', (req, res) => {
  const header = req.headers['verid-signature'] as string;
  const body = req.rawBody; // raw string body
 
  if (!verifySignature(header, body, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }
 
  console.log('Change detected:', req.body.diff.fields_changed);
  res.sendStatus(200);
});

See the Webhooks page for verification snippets in Python, Ruby, Go, and PHP.

Using the Node.js SDK

import { VeridClient } from '@verid/sdk';
 
const client = new VeridClient({
  apiKey: process.env.VERID_API_KEY!,
});
 
// Create a monitor
const monitor = await client.monitors.create({
  name: 'React New Releases',
  url: 'https://api.github.com/repos/facebook/react/releases/latest',
  schedule_interval_seconds: 3600,
  extract_config: {
    method: 'json_path',
    fields: { tag_name: '$.tag_name' },
  },
  diff_predicate: { type: 'field_changes', field: 'tag_name' },
  deliveries: [
    { type: 'webhook', url: 'https://your-app.com/webhooks/verid' },
  ],
});
 
// List monitors
const { data } = await client.monitors.list();
 
// Trigger a manual run
await client.monitors.runNow(monitor.id);

Next steps

API Reference — Full endpoint documentation
Webhooks — Signature verification in multiple languages
Recipes — Common patterns and examples

Predicates Webhooks