Overview
Webhooks let you receive HTTP callbacks when specific events occur in your workspace — like a lookup completing or an API key being created. Instead of polling the API, Encrata pushes event data directly to your server.
How it works
- You register a webhook URL in Settings → Webhooks on the dashboard.
- When a subscribed event occurs, Encrata sends a
POST request to your URL with a JSON payload.
- Each delivery is signed with HMAC-SHA256 so you can verify it came from Encrata.
Supported events
| Event | Trigger |
|---|
lookup.completed | An email lookup finishes processing |
monitor.run.completed | A monitor run finishes with changes detected |
apikey.created | A new API key is created |
apikey.revoked | An API key is revoked |
credits.low | Workspace credits drop below threshold |
credits.exhausted | Workspace credits are fully consumed |
{
"event": "lookup.completed",
"data": {
"email": "satya@microsoft.com",
"lookup_id": "lu_abc123"
},
"created_at": "2026-05-02T12:00:00Z"
}
Verifying signatures
Each webhook request includes an X-Encrata-Signature header containing the HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret.
To verify:
import hmac, hashlib
def verify_signature(payload: bytes, secret: str, signature: str) -> bool:
expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
Always verify signatures before processing webhook payloads. Never trust unverified requests.
Requirements
- Webhook URLs must use HTTPS.
- Your endpoint should return a
2xx status code within 5 seconds.
- Failed deliveries are retried with exponential backoff.
Managing webhooks
You can manage webhooks from the dashboard (Settings → Webhooks) or via the API:
| Action | Method | Endpoint |
|---|
| List webhooks | GET | /api/webhooks |
| Create webhook | POST | /api/webhooks |
| Get webhook | GET | /api/webhooks?id={id} |
| Update webhook | PUT | /api/webhooks |
| Delete webhook | DELETE | /api/webhooks |
| Test webhook | POST | /api/webhooks/test |
| List deliveries | GET | /api/webhooks/deliveries?webhook_id={id} |
Your webhook secret is shown only once when you create a webhook. Store it securely — you’ll need it to verify signatures.
