Webhooks

Webhooks transform Dregs from a monitoring tool into an automated defense system. Instead of a human reading an alert and deciding what to do, your application receives score data directly and takes action in milliseconds — quarantining accounts, throttling access, or blocking bad actors automatically, even at 3 AM on a Sunday.

What Webhooks Enable

A webhook channel sends HTTP POST requests to a URL you specify when subscribed events occur. When Dregs finishes scoring a user, your endpoint receives the results immediately. Your backend can then act on the scores: quarantine a suspicious account, throttle API access, hide content from likely spammers, require additional verification, or block a user entirely — all without human intervention.

This is the endgame of the four-stage approach. You start with manual review in the dashboard, graduate to alerts that notify your team, and finally arrive at webhooks that let your application respond autonomously.

Event Types

Each webhook channel subscribes to specific event types. Choose which events your endpoint receives:

• identity.scored — an identity's scores were updated
• identity.badges_changed — an identity's badges were added or removed
• alert.opened — a new alert was created
• alert.closed — an alert was closed

You can build targeted integrations — one webhook for score changes, another for alert notifications — without receiving events you do not care about.

Payload Format

Dregs delivers webhook payloads as JSON via HTTP POST to your configured URL. Every payload shares the same top-level structure:

{
  "event": "IDENTITY_SCORED",
  "timestamp": "2026-01-20T14:15:32.456Z",
  "channelId": "2000042",
  "data": { ... }
}

The event field identifies the event type. The data object contains the event-specific payload.

identity.scored

Dregs delivers this event every time an identity's scores are updated. The data object includes the identity ID (the same ID you pass to dregs.identify()), display fields, and all four scores as integers from 0 to 100:

{
  "event": "IDENTITY_SCORED",
  "timestamp": "2026-01-20T14:15:32.456Z",
  "channelId": "2000042",
  "data": {
    "identityId": "user_12345",
    "displayName": "Jane Cooper",
    "displayEmail": "jane@example.com",
    "displayUsername": "janecooper",
    "humanityScore": 85,
    "authenticityScore": 72,
    "uniquenessScore": 91,
    "behaviorScore": 68,
    "lastScoredAt": "2026-01-20T14:15:32.456Z"
  }
}

The identityId field is your external user ID — the same value you use with dregs.identify() and in GET /api/identities/{id}. Use it to look up the user in your database and act on the scores.

Request Headers

Every webhook request includes three custom headers:

• X-Dregs-Signature — HMAC-SHA256 hex-encoded signature of the request body, computed using your channel's signing secret
• X-Dregs-Timestamp — ISO 8601 timestamp of when the delivery was initiated
• X-Dregs-Event — the event type (e.g., IDENTITY_SCORED)

HMAC-SHA256 Signing

Dregs signs every webhook payload with your channel's signing secret using HMAC-SHA256. Your application verifies that the request genuinely came from Dregs and was not tampered with in transit.

To verify a webhook:

1. Read the raw request body as a string
2. Compute the HMAC-SHA256 of that string using your stored signing secret
3. Hex-encode the result
4. Compare it to the value in the X-Dregs-Signature header

Here is a verification example in Node.js:

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
const signature = req.headers['x-dregs-signature'];
const isValid = verifySignature(req.rawBody, signature, WEBHOOK_SECRET);

Retry Behavior

Network failures happen. If a webhook delivery fails — your server is down, returns a non-2xx status code, or times out — Dregs retries automatically, up to 3 times with exponential backoff:

• First retry: 30 seconds after the initial failure
• Second retry: 60 seconds after the first retry
• Third retry: 120 seconds after the second retry

If all three retries fail, Dregs marks the delivery as failed. View the full delivery history — including error messages and HTTP status codes — in the channel's delivery log on the Settings page.

Delivery Tracking

Dregs logs every delivery attempt with full detail: delivery status (pending, delivered, or failed), HTTP status code from your server, payload size, error message if applicable, and attempt number. This makes debugging integration issues straightforward — you see exactly what Dregs sent and exactly what your server responded.

Building Automated Responses

The real power of webhooks lies in what you do with the data. Common patterns for automated fraud response:

• Quarantine on low scores — when Humanity or Uniqueness drops below a threshold, restrict the account to read-only mode until a human reviews it.
• Rate limiting by score — adjust API rate limits from the user's current scores. Trusted users get generous limits; suspicious ones get throttled.
• Shadowban on badge assignment — when Dregs assigns a "Suspicious" badge, quietly degrade the user's experience so their abusive actions have no effect.
• Escalate to payment review — when a new user makes a purchase with low Authenticity, hold the transaction for manual review before processing.
• Feature gating — hide premium or abuse-prone features from users who have not yet earned trust through their scores.

The Path to Full Autonomy

Webhooks enable Stage 4 of the Dregs approach: fully autonomous abuse prevention. The progression:

1. Review scores manually in the dashboard.
2. Set up alert rules to notify your team via email or Slack.
3. Tune thresholds until you trust the scoring.
4. Add webhook channels so your application receives scores directly and acts on them.

At Stage 4, fraud prevention scales with your user base and works around the clock without anyone touching a keyboard.