Webhooks

Sync verify() is enough for most apps. Use webhooks to push the same decision JSON to another service.

Setup

Dashboard → Integrate → Webhooks
Add an HTTPS URL (test or live)
Copy the signing secret (whsec_…) once
Subscribe to verification.completed

Fires after a successful server POST /v2/verify for matching environment keys.

Request your endpoint receives

POST https://your-app.example.com/webhooks/keverd
Content-Type: application/json
X-Keverd-Signature: t=1710000000,v1=…
X-Keverd-Event: verification.completed
X-Keverd-Delivery: del_…

Body (JSON)

data.object is the same shape as the verify response.

{
  "id": "evt_01HZX…",
  "type": "verification.completed",
  "created": 1710000000,
  "data": {
    "object": {
      "event_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "fingerprint": "kvd_…",
      "visitor_id": "kvd_…",
      "risk_score": 42,
      "recommendation": "allow",
      "action": "allow",
      "reason": ["VPN_DETECTED"],
      "reasons": [
        {
          "code": "VPN_DETECTED",
          "explanation": "The connection appears to route through a VPN.",
          "evidence": {}
        }
      ],
      "score": 0.42,
      "trust_score": 70,
      "reputation_score": null,
      "signals": {},
      "smart_signals": {
        "vpn_detected": true,
        "action": "allow",
        "risk_score": 42
      },
      "created_at": "2026-07-25T12:00:00Z",
      "country_code": "KE",
      "country_name": "Kenya",
      "page_url": "https://example.com/login",
      "page_origin": "https://example.com",
      "location": {
        "ip": "203.0.113.10",
        "country_code": "KE",
        "country_name": "Kenya"
      },
      "ip_info": {
        "asn": "13335",
        "asn_name": "Example ISP",
        "datacenter": false
      },
      "times_seen": 3,
      "first_seen": "2026-07-01T09:00:00Z",
      "last_seen": "2026-07-25T12:00:00Z",
      "is_new": false,
      "device_history": {
        "times_seen": 3,
        "first_seen": "2026-07-01T09:00:00Z",
        "last_seen": "2026-07-25T12:00:00Z",
        "is_new": false,
        "unique_ip_count": 2,
        "unique_country_count": 1,
        "last_seen_events": []
      }
    }
  }
}

Envelope field	Type	Description
`id`	string	Webhook event id
`type`	string	Currently `verification.completed`
`created`	number	Unix timestamp (seconds)
`data.object`	object	Full verify payload

Signature

X-Keverd-Signature: t=<unix_seconds>,v1=<hmac_sha256_hex>

Also sent: X-Keverd-Event, X-Keverd-Delivery. Signed string: {t}.{raw_request_body}
HMAC-SHA256 with whsec_…, hex digest. Reject if timestamp older than 300 seconds.

Verify the signature against the raw body. Do not parse JSON before verifying.

Use constructEvent / construct_event in the Node, Python, or PHP SDKs. Failed verification throws KeverdSignatureError (Node / Python) or Keverd\KeverdSignatureError (PHP). Return 400 and do not process the payload.

Getting started

Client Side SDKs

Server Side SDKs

API Reference

Webhooks

Webhooks

Setup

Request your endpoint receives

Body (JSON)

Signature

​Webhooks

​Setup

​Request your endpoint receives

​Body (JSON)

​Signature

Webhooks

Setup

Request your endpoint receives

Body (JSON)

Signature