Skip to main content

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

Destination types

Set kind when you create a webhook. The default, generic, is the only one your application can verify and parse.
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

Payload format

Every webhook delivery sends a JSON payload in the following shape:
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):
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:

Verifying signatures

Each delivery to a generic endpoint includes these headers: 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. Use the whole signing secret, including the whsec_ prefix, as the HMAC key. To verify:
Always verify signatures before processing webhook payloads. Never trust unverified requests.

Replay and duplicates

Webhook deliveries do not include a timestamp header or delivery ID header. Encrata can retry a delivery, so your handler must tolerate duplicate event payloads. Verify the signature, acknowledge quickly, and make downstream work idempotent using identifiers in the event data when available.

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)

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.
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:
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