Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encrata.com/llms.txt

Use this file to discover all available pages before exploring further.

​
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

  1. You register a webhook URL in Settings → Webhooks on the dashboard.
  2. When a subscribed event occurs, Encrata sends a POST request to your URL with a JSON payload.
  3. Each delivery is signed with HMAC-SHA256 so you can verify it came from Encrata.

​
Supported events

EventTrigger
lookup.completedAn email lookup finishes processing
monitor.run.completedA monitor run finishes with changes detected
apikey.createdA new API key is created
apikey.revokedAn API key is revoked
credits.lowWorkspace credits drop below threshold
credits.exhaustedWorkspace credits are fully consumed

​
Payload format

Every webhook delivery sends a JSON payload in the following shape: 
{
  "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:
ActionMethodEndpoint
List webhooksGET/api/webhooks
Create webhookPOST/api/webhooks
Get webhookGET/api/webhooks?id={id}
Update webhookPUT/api/webhooks
Delete webhookDELETE/api/webhooks
Test webhookPOST/api/webhooks/test
List deliveriesGET/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.