Webhooks

Register an endpoint and the events you want. The secret is shown once.

POST /v1/webhook_endpoints
{ "url": "https://ats.example.com/primarycheck",
  "events": ["verification.completed", "verification.updated", "monitor.changed", "dispute.resolved", "consent.signed"] }

Payload

{ "id": "evt_…", "type": "verification.completed", "createdAt": "2026-11-03T14:05:11Z",
  "data": { "object": { "id": "ver_…", "status": "complete", "claims": [ … ] } } }

Verify the signature

Header PrimaryCheck-Signature: t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, "<t>.<raw body>"). Reject if the timestamp is more than five minutes off. The SDKs ship verify_signature / verifySignature (timing-safe compare, returns the parsed event); the plain versions below are the same algorithm.

from primarycheck import webhooks, SignatureVerificationError

try:
    event = webhooks.verify_signature(raw_body, request.headers["PrimaryCheck-Signature"], WEBHOOK_SECRET)
except SignatureVerificationError:
    return Response(status_code=400)
# event == {"id": "evt_…", "type": "verification.completed", "data": {"object": {...}}}

Retries and replay

Non-2xx responses are retried at 1 m, 5 m, 30 m, 2 h, 6 h and 24 h, then marked failed. Every delivery is visible under GET /v1/webhook_endpoints/{id}/deliveries and can be retried from the dashboard.