API Reference
/api/v1/webhooks
Verify webhook signatures and configure real-time fraud event notifications.
Webhooks deliver real-time notifications when fraud events occur. Use the /webhooks endpoint to verify incoming webhook signatures, and configure webhook subscriptions from the Dashboard.
Webhook verification requires a secret key (sk_) with webhooks:read permission.
Verify a Webhook Signature
POST /api/v1/webhooksbash
curl -X POST https://verifystack.io/api/v1/webhooks \
-H "X-API-Key: sk_live_xxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"payload": "{...}",
"signature": "sha256=abc123...",
"timestamp": "2026-02-14T10:30:00Z",
"secret": "whsec_xxxxxxxx"
}'Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| payload | string | Yes | The raw webhook payload body |
| signature | string | Yes | The signature from the webhook header |
| timestamp | string | Yes | The timestamp from the webhook header |
| secret | string | Yes | Your webhook signing secret |
Response (200 OK)
Verification resultjson
{
"success": true,
"data": {
"valid": true,
"reason": "Signature verified"
},
"meta": { "requestId": "req_xxx", "latencyMs": 2 }
}Supported Events
| Event | Description |
|---|---|
| decision.allow | A request was allowed |
| decision.challenge | A request requires additional verification |
| decision.deny | A request was denied |
| case.created | A fraud case was auto-created |
| case.resolved | A case was resolved by an analyst |
| policy.triggered | A policy rule matched |
| feedback.received | Ground-truth feedback was submitted |
| anomaly.detected | Anomalous behavior pattern detected |
Delivery Methods
| Method | Description |
|---|---|
| http | Standard HTTPS POST (default) |
| websocket | WebSocket stream |
| aws_sns | AWS SNS topic |
| aws_sqs | AWS SQS queue |
| kafka | Apache Kafka topic |
Webhook Signature Verification
All HTTP webhooks include a signature header for verification:
Verify webhook signaturejavascript
import crypto from 'crypto';
function verifyWebhook(payload, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}List Webhooks
GET /api/v1/webhooksbash
curl https://verifystack.io/api/v1/webhooks \
-H "X-API-Key: sk_live_xxxxxxxxx"