Webhooks

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 on the dashboard (Settings → Webhooks) or with POST /api/webhooks.
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.

Destination types

Set kind when you create a webhook. The default, generic, is the only one your application can verify and parse.

Kind	Receives	Signed
`generic`	The raw `{event, data, created_at}` JSON envelope	Yes, `X-Encrata-Signature`
`slack`	`{"text": "..."}` posted to a Slack incoming webhook	No
`discord`	`{"content": "..."}` posted to a Discord webhook	No
`telegram`	A Bot API `sendMessage` call	No

Chat destinations get a short human-readable summary, not the JSON envelope, and they carry no signature. Everything below about payloads and verification applies to generic webhooks.

Supported events

Event	Trigger
`lookup.completed`	An email lookup finishes processing
`bulk.completed`	A bulk job finishes processing
`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
`monitor.run.completed`	A monitor run finishes and detected at least one change
`monitor.alert.high_value`	A monitor run surfaced one or more high-value alerts

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"
}

A bulk.completed event reports the finished job. When the job was created with download_link=true, the payload also carries a download_url you can fetch with your API key to get the result file (see Bulk Operations):

{
  "event": "bulk.completed",
  "data": {
    "job_id": "a1b2c3d4-0000-0000-0000-000000000000",
    "kind": "gender",
    "status": "completed",
    "processed": 5000,
    "total": 5000,
    "download_url": "https://developer.encrata.com/api/jobs/exports/download?kind=gender&id=a1b2c3d4-0000-0000-0000-000000000000&format=csv&filter=all"
  },
  "created_at": "2026-05-02T12:00:00Z"
}

A monitor.run.completed event fires when a monitor run detects at least one change. A monitor.alert.high_value event fires separately when a run surfaces high-value alerts, and carries the list under alerts:

{
  "event": "monitor.run.completed",
  "data": {
    "monitor_id": "m_abc123",
    "monitor_name": "Competitor hires",
    "run_id": "run_def456",
    "total_records": 100,
    "changes_detected": 3,
    "credits_used": 3
  },
  "created_at": "2026-05-02T12:00:00Z"
}

Verifying signatures

Each delivery to a generic endpoint includes these headers:

Header	Value
`X-Encrata-Signature`	HMAC-SHA256 hex digest of the raw request body, keyed with your webhook secret
`X-Encrata-Event`	The event type in this delivery, for example `lookup.completed`
`User-Agent`	`Encrata-Webhooks/1.0`

Compute the digest over the raw bytes of the body. Parsing and re-serializing the JSON changes the bytes and the signature will not match. 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)

const crypto = require("crypto");

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

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func VerifySignature(payload []byte, secret, signature string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(payload)
    expected := hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signature))
}

Always verify signatures before processing webhook payloads. Never trust unverified requests.

Receiver example

A complete endpoint that verifies the signature, acknowledges fast, then routes each event. It reads the raw body so the HMAC matches byte-for-byte.

Node.js (Express)

const express = require("express");
const crypto = require("crypto");

const app = express();
const WEBHOOK_SECRET = process.env.ENCRATA_WEBHOOK_SECRET;

app.post("/webhooks/encrata", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-encrata-signature"] || "";
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");

  if (
    signature.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  ) {
    return res.status(401).send("Invalid signature");
  }

  // Acknowledge fast, then do the work.
  res.sendStatus(200);

  const { event, data } = JSON.parse(req.body);
  switch (event) {
    case "lookup.completed":
      console.log(`Lookup ready for ${data.email}`);
      break;
    case "bulk.completed":
      // data.download_url is present when the job was created with download_link=true
      console.log(`Bulk ${data.kind} job ${data.job_id} finished: ${data.processed}/${data.total}`);
      break;
    case "apikey.created":
    case "apikey.revoked":
      console.log(`API key event: ${event}`);
      break;
    case "credits.low":
      console.warn("Workspace credits are running low.");
      break;
    case "credits.exhausted":
      console.error("Workspace credits exhausted. Top up to resume lookups.");
      break;
    case "monitor.run.completed":
      console.log(`Monitor ${data.monitor_name}: ${data.changes_detected} change(s) detected`);
      break;
    case "monitor.alert.high_value":
      console.warn(`Monitor ${data.monitor_name}: ${data.alert_count} high-value alert(s)`);
      break;
  }
});

app.listen(3000);

Delivery and retries

Webhook URLs must use HTTPS and must resolve to a public address. Private, loopback, and link-local addresses are rejected at creation.
Encrata waits 10 seconds for each attempt. Return a 2xx status before then, and do your slow work after acknowledging.
A delivery gets 4 attempts in total.

Attempt	Delay before it runs
1	Immediate
2	30 seconds
3	2 minutes
4	10 minutes

If your endpoint returns a Retry-After header asking for longer, Encrata honours it up to 15 minutes. After the fourth attempt the delivery is marked failed and is not retried. Check what actually happened with list deliveries.

Managing webhooks

Manage webhooks from the dashboard (Settings → Webhooks) or through the API:

Action	Method	Endpoint	Role
List webhooks	`GET`	`/api/webhooks`	Any
Get webhook	`GET`	`/api/webhooks/{id}`	Any
Create webhook	`POST`	`/api/webhooks`	`admin`
Update webhook	`PUT`	`/api/webhooks`	`admin`
Delete webhook	`DELETE`	`/api/webhooks/{id}`	`admin`
Test webhook	`POST`	`/api/webhooks/test`	`admin`
List deliveries	`GET`	`/api/webhooks/deliveries?webhook_id={id}`	Any

Your signing secret is returned when you create a generic webhook. A workspace admin can read it again with GET /api/webhooks/{id}. It is never included in the list response.

Next steps

Create a webhook

Test your endpoint

Send a synthetic event and read the response.

Debug deliveries

Inspect the last 50 attempts for any webhook.

Bulk operations

Use bulk.completed to collect finished jobs.

Account & team

Run your integration

Use cases

Integrations

AI tools

Agent-ready docs

auth.md

Overview

How it works

Destination types

Supported events

Payload format

Verifying signatures

Receiver example

Delivery and retries

Managing webhooks

Next steps

Create a webhook

Test your endpoint

Debug deliveries

Bulk operations

​Overview

​How it works

​Destination types

​Supported events

​Payload format

​Verifying signatures

​Receiver example

​Delivery and retries

​Managing webhooks

​Next steps

Create a webhook

Test your endpoint

Debug deliveries

Bulk operations

Overview

How it works

Destination types

Supported events

Payload format

Verifying signatures

Receiver example

Delivery and retries

Managing webhooks

Next steps