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
Usecategory.* 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
- In the tenant console, go to Settings > Webhooks.
- Click Add endpoint.
- Enter a name, your HTTPS destination URL, and select the event types you want to receive.
- Click Create.
Via the API
Request
Response
Listing endpoints
Retrieve all webhook endpoints for your tenant:Request
Verifying signatures
Every webhook request includes a signature header for verification. Always verify signatures before processing events. Signature format:t is the Unix timestamp and v1 is the HMAC-SHA256 hex digest.
Verification steps:
- Extract
t(timestamp) andv1(signature) from the header. - Reject the request if the timestamp is more than 5 minutes old.
- Concatenate
{timestamp}.{raw_request_body}to form the signing string. - Compute HMAC-SHA256 of the signing string using your endpoint secret.
- Compare the computed digest to
v1using a constant-time comparison.
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
Rotating secrets
If your webhook secret is compromised, rotate it immediately:- In the tenant console, go to Settings > Webhooks and click on the endpoint.
- Click Rotate secret.
- Copy the new secret — the old secret stops working immediately.
Request
Testing webhooks
Send a test event to verify your endpoint is working:- In the tenant console, go to Settings > Webhooks and click on the endpoint.
- Click Send test.
- A
webhook.testevent is sent to your URL using the full signing and delivery pipeline.
Request
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 torisk.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
- 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-Idheader 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.

