Documentation & Tutorials

How-To Guides

Step-by-step tutorials for getting the most out of SapherData — from your first API call to building advanced threat intelligence pipelines.

Start Here

Your first SapherData API call in 5 minutes

Generate an API key, make your first domain lookup, and understand the JSON response. No setup required — works directly in your terminal.

1
Create a free account & generate your API key
2
Make your first GET /domain/{domain} request
3
Understand the score, WHOIS, and DNS response
4
Try the bulk endpoint with multiple domains
cURL
# 1. Make your first API call
curl https://api.sapherdata.com/v2
     /domain/stripe.com \
  -H "X-API-Key: YOUR_KEY"

# Response
{
  "domain": "stripe.com",
  "score": 9.4,
  "status": "active",
  "blacklisted": false
}
All Guides
View all →
API Authentication — keys, scopes & best practices
How to authenticate API requests, manage key scopes, rotate keys securely, and use test vs live keys safely in production environments.
5 minBeginner
How to read a Domain Profile — tab-by-tab walkthrough
A complete walkthrough of every section in a SapherData domain profile — score ring, WHOIS, DNS, SSL, Network, and Intelligence tabs explained.
6 minBeginner
Bulk domain lookup — batching 100 domains per request
How to use the POST /domain/bulk endpoint, handle credit consumption, implement pagination, and process large domain lists efficiently.
7 minIntermediate
Building a phishing detector with domain score + WHOIS age
Combine domain score, registration age, blacklist signals, and typosquat detection to build a real-time phishing domain classifier.
12 minAdvanced
Step-by-Step
API & Integration
How to set up webhooks for domain status change alerts
8 min read·Updated Apr 2026·Intermediate
1
Create a webhook endpoint on your server
Your endpoint must accept POST requests and return a 200 HTTP response within 5 seconds. SapherData retries failed deliveries up to 3 times with exponential backoff.
POST https://yourdomain.com/webhooks/sapherdata
2
Register the webhook in your dashboard
Go to Dashboard → Webhooks → Add Endpoint. Paste your URL, select the events you want to subscribe to (status_change, expiry_alert, blacklist_added), and save.
3
Verify the webhook signature
Every SapherData webhook includes an X-MXY-Signature header. Verify it against your webhook secret to prevent spoofed requests.
const sig = req.headers['x-mxy-signature'];
const expected = hmac('sha256', secret, body);
if (sig !== expected) return res.status(401).send();
4
Handle the event payload
Parse the JSON body to get the event type, domain name, old and new values, and timestamp. Process asynchronously — always respond 200 first, then do your processing.
{ "event": "blacklist_added", "domain": "example.com", "timestamp": "2026-04-14T10:32:00Z" }