feat(webhooks): expand webhook event-type detection for attestations and scores (#519)

docs/webhook-example.ts

@@ -2,6 +2,10 @@
  * Example: Webhook integration with identity state sync via transactional outbox.
  */
 
+import { createIdentityStateSync } from '../src/listeners/identityStateSync.js'
+import { createWebhookService } from '../src/services/webhooks/service.js'
+import { MemoryWebhookStore } from '../src/services/webhooks/memoryStore.js'
+import { emitWebhookForStateChange, emitWebhookForScoreChange, emitWebhookForAttestationChange } from '../src/listeners/webhookIntegration.js'
 import type { Queryable } from '../src/db/repositories/queryable.js'
 import { emitWebhookForStateChange } from '../src/listeners/webhookIntegrationOutbox.js'
 import type { ContractReader, IdentityState, IdentityStateStore } from '../src/listeners/types.js'

docs/webhooks.md

@@ -7,6 +7,9 @@ Webhook system for delivering bond lifecycle events to registered endpoints.
 - `bond.created` - Bond becomes active
 - `bond.slashed` - Bond amount decreases while active
 - `bond.withdrawn` - Bond becomes inactive with zero amount
+- `attestation.added` - A new attestation was added
+- `attestation.revoked` - An attestation was revoked
+- `score.updated` - Reputation score was recomputed
 
 ## Payload Format
 

src/listeners/webhookDetection.ts

@@ -0,0 +1,22 @@
+import type { IdentityState } from './types.js'
+import type { WebhookEventType } from '../services/webhooks/index.js'
+
+export function detectEventType(
+  oldState: IdentityState | null,
+  newState: IdentityState
+): WebhookEventType | null {
+  if ((!oldState || !oldState.active) && newState.active) {
+    return 'bond.created'
+  }
+  if (oldState?.active && !newState.active && newState.bondedAmount === '0') {
+    return 'bond.withdrawn'
+  }
+  if (
+    oldState?.active &&
+    newState.active &&
+    BigInt(newState.bondedAmount) < BigInt(oldState.bondedAmount)
+  ) {
+    return 'bond.slashed'
+  }
+  return null
+}

src/listeners/webhookIntegration.ts

@@ -1,8 +1,7 @@
 import type { IdentityState } from './types.js'
-import type { WebhookService } from '../services/webhooks/index.js'
-import { detectEventType } from './webhookEventDetection.js'
+import { detectEventType } from './webhookDetection.js'
+import type { WebhookService, WebhookEventType } from '../services/webhooks/index.js'
 
-export { detectEventType } from './webhookEventDetection.js'
 
 /**
  * Emit webhook for identity state change via direct service call.
@@ -29,3 +28,28 @@ export async function emitWebhookForStateChange(
     })
   }
 }
+export async function emitWebhookForAttestationChange(
+  webhookService: WebhookService,
+  eventType: 'attestation.added' | 'attestation.revoked',
+  payload: { address: string; attestationId?: string; verifier?: string; weight?: number; claim?: string }
+): Promise<void> {
+  await webhookService.emit(eventType, {
+    address: payload.address,
+    ...payload
+  })
+}
+
+export async function emitWebhookForScoreChange(
+  webhookService: WebhookService,
+  address: string,
+  oldScore: number | null,
+  newScore: number
+): Promise<void> {
+  if (oldScore !== newScore) {
+    await webhookService.emit('score.updated', {
+      address,
+      score: newScore
+    })
+  }
+}
+

src/listeners/webhookIntegrationOutbox.ts

@@ -1,5 +1,7 @@
 import type { Queryable } from '../db/repositories/queryable.js'
 import type { IdentityState } from './types.js'
+import type { WebhookEventType } from '../services/webhooks/index.js'
+import { detectEventType } from './webhookDetection.js'
 import { outboxEmitter } from '../db/outbox/emitter.js'
 import { detectEventType } from './webhookEventDetection.js'
 
@@ -35,3 +37,38 @@ export async function emitWebhookForStateChange(
     })
   }
 }
+export async function emitWebhookForAttestationChange(
+  db: any,
+  eventType: 'attestation.added' | 'attestation.revoked',
+  payload: { address: string; attestationId?: string; verifier?: string; weight?: number; claim?: string }
+): Promise<void> {
+  await outboxEmitter.emit(db, {
+    aggregateType: 'identity',
+    aggregateId: payload.address,
+    eventType,
+    payload: {
+      address: payload.address,
+      ...payload
+    },
+  })
+}
+
+export async function emitWebhookForScoreChange(
+  db: any,
+  address: string,
+  oldScore: number | null,
+  newScore: number
+): Promise<void> {
+  if (oldScore !== newScore) {
+    await outboxEmitter.emit(db, {
+      aggregateType: 'identity',
+      aggregateId: address,
+      eventType: 'score.updated',
+      payload: {
+        address,
+        score: newScore
+      },
+    })
+  }
+}
+

src/services/webhooks/types.ts

@@ -1,9 +1,7 @@
 /**
  * Webhook event types for bond lifecycle.
  */
-export type WebhookEventType = 'bond.created' | 'bond.slashed' | 'bond.withdrawn'
-  | 'attestation.created'
-  | 'attestation.revoked'
+export type WebhookEventType = 'bond.created' | 'bond.slashed' | 'bond.withdrawn' | 'attestation.added' | 'attestation.revoked' | 'score.updated' | 'attestation.added' | 'attestation.revoked' | 'score.updated'
 
 /**
  * Webhook configuration for a registered endpoint.
@@ -58,18 +56,19 @@ export interface WebhookPayload {
   event: WebhookEventType
   /** ISO timestamp when event occurred. */
   timestamp: string
-  /** Event data (identity state, or a list of items for chunked payloads). */
-  data: Record<string, unknown> | unknown[]
-  /** Chunk ID for chunked payloads (optional). */
-  chunkId?: string
-  /** Index of this chunk (0-based). */
-  chunkIndex?: number
-  /** Total number of chunks. */
-  totalChunks?: number
-  /** Flag indicating payload was truncated. */
-  payloadTruncated?: boolean
-  /** URL to fetch remaining data (optional). */
-  paginationUrl?: string
+  /** Event data (identity state). */
+  data: {
+    address: string
+    bondedAmount: string
+    bondStart: number | null
+    bondDuration: number | null
+    active: boolean
+    attestationId?: string
+    verifier?: string
+    weight?: number
+    claim?: string
+    score?: number
+  }
 }
 
 /**