Skip to main content
Webhooks let your application receive automatic notifications when events happen in your Truthlocks account — for example, when an attestation is minted, a key is rotated, or a verification fails. Instead of polling the API for changes, your server receives an HTTP POST request with the event details.

How it works

1

Register an endpoint

Add a webhook endpoint in Settings > Webhooks in the tenant console. Provide a publicly reachable HTTPS URL and choose which event types you want to receive.
2

Receive events

When a matching event occurs, Truthlocks sends an HTTP POST request to your URL with a JSON payload describing the event.
3

Verify the signature

Each request includes an HMAC-SHA256 signature in the X-Truthlocks-Signature header. Verify it using the endpoint secret to confirm the request came from Truthlocks.
4

Respond with 200

Return an HTTP 200 status code to acknowledge receipt. If your endpoint fails or times out, Truthlocks retries with exponential backoff.

Event types

Events are grouped into categories. You can subscribe to individual events or use a wildcard (attestation.*) to receive all events in a category.

Wildcard filters

Use category.* to subscribe to every event in a category. For example, attestation.* matches attestation.created, attestation.revoked, attestation.expired, and attestation.superseded.

Endpoint limits by plan

The number of webhook endpoints you can create depends on your plan tier: Need more endpoints? Contact your account manager or upgrade your plan in Settings > Billing.

Creating an endpoint

  1. In the tenant console, go to Settings > Webhooks.
  2. Click Add endpoint.
  3. Enter a name, your HTTPS destination URL, and select the event types you want to receive.
  4. Click Create.
The console displays your endpoint secret once. Copy it immediately — you cannot retrieve it later.

Via the API

Request
Response

Listing endpoints

Retrieve all webhook endpoints for your tenant:
Request
See the full API reference for response details.

Verifying signatures

Every webhook request includes a signature header for verification. Always verify signatures before processing events. Signature format:
Where t is the Unix timestamp and v1 is the HMAC-SHA256 hex digest. Verification steps:
  1. Extract t (timestamp) and v1 (signature) from the header.
  2. Reject the request if the timestamp is more than 5 minutes old.
  3. Concatenate {timestamp}.{raw_request_body} to form the signing string.
  4. Compute HMAC-SHA256 of the signing string using your endpoint secret.
  5. Compare the computed digest to v1 using a constant-time comparison.
Always use a constant-time comparison function (like crypto.timingSafeEqual or hmac.compare_digest) to prevent timing attacks.

Request headers

Every webhook delivery includes these headers:

Retry behavior

If your endpoint returns a non-2xx status code or doesn’t respond within 5 seconds, Truthlocks retries the delivery with exponential backoff: Delays include up to 30% jitter. After 8 total attempts (1 initial + 7 retries), the delivery is marked as failed. You can view delivery attempts and failure details in Settings > Webhooks by clicking on an endpoint, or query them via the API:
Request
See the list deliveries API reference for response details.

Rotating secrets

If your webhook secret is compromised, rotate it immediately:
  1. In the tenant console, go to Settings > Webhooks and click on the endpoint.
  2. Click Rotate secret.
  3. Copy the new secret — the old secret stops working immediately.
You can also rotate via the API:
Request

Testing webhooks

Send a test event to verify your endpoint is working:
  1. In the tenant console, go to Settings > Webhooks and click on the endpoint.
  2. Click Send test.
  3. A webhook.test event is sent to your URL using the full signing and delivery pipeline.
Via the API:
Request
The event_type and payload fields are optional — they default to webhook.test and a basic status payload if omitted.

Risk signal notifications

You can receive real-time webhook notifications whenever a risk signal is created by any of the five Anti-Fraud Identity Firewall detection paths — direct ingestion, event normalization, deepfake scanning, ATO detection, and velocity scoring. Subscribe to risk.signal.* to receive all risk signal events, or subscribe to risk.signal.created or risk.signal.escalated individually.

Example payload

Responding to risk signals

Use risk signal webhooks to trigger automated responses — block a user session, notify your security team, or escalate to a fraud case — without polling the API.
Risk signal webhooks fire for signals created by all five detection paths. The signal_source field in the payload tells you which path generated the signal — external, event_normalization, deepfake, ato, or velocity.

Best practices

Respond to webhooks quickly. Do your heavy processing asynchronously after returning a 200 response to avoid timeouts and retries.
  • Verify every signature. Never skip signature verification, even in development.
  • Use a message queue. Enqueue incoming events and process them in a worker to avoid blocking the HTTP response.
  • Handle duplicates. Use the X-Truthlocks-Event-Id header to deduplicate events in case of retries.
  • Monitor delivery failures. Check the deliveries tab in the console regularly for failed or dead deliveries.
  • Keep secrets secure. Store your webhook secret in environment variables, not in source code.