Webhooks

Webhooks are what 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 make decisions based 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 ultimately arrive at webhooks that let your application respond autonomously.

Event Subscriptions

Each webhook channel subscribes to specific event types. You choose which events your endpoint should receive. For example, subscribing to identity.scored means your URL will receive a POST request every time an identity's scores are updated.

This lets you build targeted integrations — one webhook for score changes, another for alert notifications — without receiving events you don't care about.

Payload Format

Webhook payloads are delivered as JSON via HTTP POST to your configured URL. Each payload includes the event type, timestamp, and the relevant data for that event — identity scores, alert details, or whatever the subscribed event provides. The structure is consistent and documented, so your integration code can parse it reliably.

HMAC-SHA256 Signing

Every webhook payload is signed with your channel's secret key using HMAC-SHA256. This lets your application verify that the request genuinely came from Dregs and was not tampered with in transit. The signature is included in the request headers.

To verify a webhook on your end, compute the HMAC-SHA256 of the raw request body using your stored secret and compare it to the signature in the header. If they match, the payload is authentic. Most languages have HMAC libraries that make this straightforward.

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. Failed deliveries are retried 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, the delivery is marked as failed. You can see the full delivery history — including error messages and HTTP status codes — in the channel's delivery log on the Settings page.

Delivery Tracking

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

Building Automated Responses

The real power of webhooks is what you do with the data. Here are common patterns for automated fraud response:

• Quarantine on low scores — when Humanity or Uniqueness drops below a threshold, automatically restrict the account to read-only mode until a human reviews it.
• Rate limiting by score — adjust API rate limits based on 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 haven't established trust through their scores.

The Path to Full Autonomy

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

1. You start by reviewing scores manually in the dashboard.
2. You set up alert rules to notify your team via email or Slack.
3. You fine-tune thresholds until you trust the scoring.
4. You 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. That is the endgame.