Skip to main content

Overview

Webhooks allow you to receive real-time notifications when events occur in the ZKScore system.

Supported Events

Score Events

  • score.updated: User score changed
  • score.calculated: New score calculated
  • score.breakdown.updated: Score breakdown changed

Achievement Events

  • achievement.claimed: User claimed an achievement
  • achievement.progress.updated: Achievement progress changed
  • achievement.created: New achievement created

Identity Events

  • identity.minted: New identity minted
  • identity.activated: Identity activated
  • identity.updated: Identity information updated

Attestation Events

  • attestation.created: New attestation created
  • attestation.revoked: Attestation revoked
  • attestation.verified: Attestation verified

Webhook Payload

All webhook payloads follow this structure:

Setting Up Webhooks

Webhook Security

Signature Verification

Best Practices

  1. Verify Signatures: Always verify webhook authenticity
  2. Handle Duplicates: Implement idempotency
  3. Process Asynchronously: Use queues for heavy processing
  4. Log Events: Keep audit trails
  5. Test Thoroughly: Use webhook testing tools