guidewire-webhooks-integrations

What this skill does

# Guidewire Webhooks and Event Integrations

## Overview

Wire Guidewire's event system into downstream consumers — analytics warehouses, fraud-detection services, broker-portal cache invalidators, customer-notification services. Guidewire emits **App Events** (typed business events fired on entity-state transitions); they are configured server-side in Gosu and routed to a destination (SQS, Kafka, or webhook URL). The consumer side has its own production failure modes that this skill addresses.

Five production failures this skill prevents:

1. **Event registered nowhere** — code subscribes to a `claim.bound` event that was never registered in Gosu; consumer waits forever; no error surfaces because there's nothing to error on.
2. **Duplicate processing** — the queue redelivers a message after consumer ack timeout; consumer creates a duplicate downstream record (duplicate notification, duplicate analytics row).
3. **Out-of-order arrival** — events for the same claim arrive in the wrong order (`claim.reserve.changed` before `claim.created`); consumer rejects the reserve event because the parent claim does not yet exist locally.
4. **Quiet event loss** — consumer was down for 30 minutes; events that fired during that window are gone; nobody notices until a downstream report is missing rows.
5. **Back-pressure cascade** — producer (Guidewire) emits faster than the consumer drains the queue; queue depth grows; eventually the destination's queue retention expires and events are dropped.

## Prerequisites

- A working integration per `guidewire-install-auth` and `guidewire-sdk-patterns`
- Access to the InsuranceSuite config zone for editing Gosu / messaging-destination XML
- A destination ready to receive events (AWS SQS queue + dead-letter queue, an HTTPS webhook endpoint, or a Kafka topic)
- The consumer service has its own datastore for idempotency keys (Redis with TTL ≥ 7d works; a database table also works)

## Instructions

Build the integration in this order. Each step targets one of the five production failures listed in Overview.

### 1. Register the App Event in Gosu

Events not registered do not fire. The registration lives in `gw.api.messaging.MessageEvents` (or carrier-customized equivalent) and pairs an event code with a Gosu callback that decides whether to emit, and what payload.

```gosu
// modules/configuration/gsrc/com/acme/messaging/ClaimEventBuilder.gs
package com.acme.messaging

uses gw.api.messaging.MessageContext
uses entity.Claim

class ClaimEventBuilder {
  static function buildClaimStatusChangedEvent(ctx: MessageContext, claim: Claim): String {
    return new gw.api.web.json.JsonObject() {{
      put("eventType", "claim.status.changed")
      put("messageId", java.util.UUID.randomUUID().toString())
      put("eventTime", java.time.Instant.now().toString())
      put("claimId", claim.PublicID)
      put("claimNumber", claim.ClaimNumber)
      put("oldStatus", ctx.PreviousValue?.toString())
      put("newStatus", claim.State.Code)
      put("policyNumber", claim.Policy.PolicyNumber)
    }}.toString()
  }
}
```

Register the destination in `config/Messaging.xml` so the InsuranceSuite messaging engine knows which channel (SQS, webhook, Kafka) routes the event. Without that XML entry, the Gosu callback exists but never fires.

### 2. Idempotent consumer keyed on messageId

Every event payload includes a `messageId` (a UUID generated by the producer). The consumer dedups on it before processing. The dedup window must exceed the queue's max-redelivery-window — for SQS with 24-hour message retention, dedup TTL ≥ 7 days is safe.

```typescript
async function handleEvent(msg: SqsMessage): Promise<void> {
  const event = JSON.parse(msg.Body);
  const seen = await redis.set(`evt:${event.messageId}`, "1", "EX", 7 * 86400, "NX");
  if (!seen) {
    return; // already processed; ack and skip
  }
  await processEvent(event); // your business logic
}
```

`SET ... NX` (set-if-not-exists) makes the dedup atomic — concurrent workers cannot both decide a duplicate is novel.

### 3. Out-of-order tolerance via state-machine validation

Events for the same claim can arrive in arbitrary order. Consumer must tolerate without rejecting.

```typescript
async function processEvent(event: Event): Promise<void> {
  const local = await getLocalClaim(event.claimId);
  switch (event.eventType) {
    case "claim.created":
      if (!local) await createLocalClaim(event);
      break;
    case "claim.status.changed":
      if (!local) {
        await deferEvent(event, "waiting-on-claim-created");
        return;
      }
      await applyStatusChange(local, event);
      break;
  }
}
```

The `deferEvent` helper writes the event to a holding table; a periodic re-processor retries deferred events when their dependencies might have arrived. Events older than a TTL (e.g., 24h) escalate to manual review — a deferred event still missing dependencies after a day indicates a real producer bug.

### 4. Checkpoint and replay for backfill / recovery

If the consumer goes down or a downstream system needs to be rebuilt, replay events from a checkpoint. Guidewire's messaging system retains events server-side per the configured retention; in addition, the consumer should persist its own checkpoint (last-processed `eventTime` per event type).

```typescript
await db.upsert("event_checkpoint", {
  consumer: "broker-portal-cache",
  event_type: "policy.bound",
  last_event_time: maxEventTimeInBatch,
  updated_at: new Date(),
});

async function replay(consumer: string, eventType: string, fromTime: Date): Promise<void> {
  const events = await fetch(`${BASE}/cc/rest/v1/events?eventType=${eventType}&since=${fromTime.toISOString()}`);
  for await (const e of events) await handleEvent({ Body: JSON.stringify(e) } as any);
}
```

Replay must be idempotent — that is why the consumer's `messageId` dedup must outlive the replay window.

### 5. Back-pressure handling

If queue depth grows past a threshold, the consumer is losing ground. Three responses, pre-baked rather than improvised at 3am:

```yaml
# CloudWatch alarm: SQS queue depth > 10000 for 15min
on-alarm:
  - autoscale: increase consumer replicas to 4x
  - if not catching up after 15min more:
    - emit metric `consumer-saturation` to incident pipeline
    - on-call paged
  - if queue retention near expiry:
    - last-resort: emergency cap on producer-side rate limit
```

The autoscale path handles transient bursts; the cap path is for sustained saturation that needs a producer-side conversation.

## Output

A production-grade event integration ships with all of the following:

- App Events registered in Gosu and `Messaging.xml` for every business event the consumer needs; absent registrations explicitly documented as out-of-scope.
- Consumer-side idempotency keyed on `messageId` with TTL ≥ queue retention window.
- Out-of-order tolerance: consumer processes events that arrive in any order without rejecting; deferred events held in a queue with TTL escalation.
- Per-consumer checkpoint persisted; replay tooling that consumes from the checkpoint forward and is safe under retry.
- Back-pressure response: queue-depth alarm wired to autoscale; saturation playbook documented; emergency producer cap available.

## Examples

### Example 1 — Gosu event builder for a policy renewal event

```gosu
class RenewalEventBuilder {
  static function build(ctx: MessageContext, policy: Policy): String {
    return new gw.api.web.json.JsonObject() {{
      put("eventType", "policy.renewed")
      put("messageId", java.util.UUID.randomUUID().toString())
      put("eventTime", java.time.Instant.now().toString())
      put("policyNumber", policy.PolicyNumber)
      put("renewedFrom", policy.RenewedFromPolicy?.PolicyNumber)
      put("effectiveDate", policy.EffectiveDate.toString())
      put("totalPremium", policy.TotalPremium.Amount.toString())
    }}.toString()
  }
}
```

### Example 2 — Out-of-order handling for claim events

```typescript
case "cla