SKSmart KYCDeveloper documentation

Webhooks

Use webhooks to receive verification outcomes without repeatedly polling session detail. Endpoint management is available now; the public signing-header and signature-algorithm contract still needs backend documentation before customers can implement cryptographic verification.

Register an endpoint

Create an HTTPS receiver and subscribe only to events your application processes.

{
  "description": "Primary production webhook",
  "targetUrl": "https://client.example.com/webhooks/verification",
  "subscribedEvents": [
    "verification.completed",
    "verification.failed"
  ]
}

Send this payload to POST /api/v1/webhooks/endpoints using current product authentication.

Save the signing secret immediately

The create response includes rawSecret once. Store it in your secret manager before leaving the response flow. Later endpoint reads return secretPrefix, not the recoverable secret.

Rotating with POST /api/v1/webhooks/endpoints/:endpointId/rotate-secret also returns the new raw secret once. Update receivers before relying on the rotated value.

Acknowledge deliveries quickly

Your endpoint should:

  1. Read the raw request body.
  2. Verify the signature after the backend publishes the header and algorithm contract.
  3. Deduplicate using eventId.
  4. Persist or enqueue the event.
  5. Return a successful response quickly.
  6. Process business effects asynchronously and idempotently.

Do not copy a generic HMAC implementation into production yet. The current backend handoff does not define the signature header, timestamp tolerance, canonical signed bytes, or digest encoding.

Event payload fields

Delivery records currently expose fields including:

  • eventId
  • eventType
  • occurredAt
  • verificationId
  • sessionToken
  • status
  • decision
  • riskScore
  • reasonCodes
  • failureCode

Use eventId for deduplication. Use status, decision, failureCode, and reasonCodes for stable application logic.

Delivery troubleshooting

Inspect GET /api/v1/webhooks/deliveries for delivery status, attempt number, response status, and endpoint association. Delivery history is currently read-only and replay is not part of the customer contract yet.