guidewire-webhooks-integrations

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.

// 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.

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.

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).

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:

# 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

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

case "claim.payment.created":
  const claim = await getLocalClaim(event.claimId);
  if (!claim) {
    await deferEvent(event, "missing claim parent");
    return;
  }
  if (!claim.exposures.find(e => e.id === event.exposureId)) {
    await deferEvent(event, "missing exposure parent");
    return;
  }
  await applyPayment(claim, event);
  break;

Example 3 — Checkpoint-based replay

# Replay all policy.bound events since last successful checkpoint
LAST=$(psql -tAc "SELECT last_event_time FROM event_checkpoint WHERE consumer='broker-portal' AND event_type='policy.bound'")
node scripts/replay.js --consumer=broker-portal --type=policy.bound --since="$LAST"

Error Handling

Symptom	Cause	Solution
Event subscription set up but no events arriving	Gosu registration missing or Messaging.xml entry missing	confirm both; the Gosu callback alone does not route
Same downstream record created twice	consumer not deduping on messageId	wire the Redis SET NX dedup; backfill cleanup of duplicates is painful
Consumer rejects event with "parent not found"	out-of-order arrival; parent event has not been processed yet	use the deferred-events queue; do not reject
Events lost during consumer outage	no replay tooling	implement checkpoint + replay; without it, outages are data-loss events
Queue depth growing 24/7	producer faster than consumer	scale consumer; if scaling does not help, partition by entity-id
Replay creates duplicates downstream	consumer dedup TTL too short, or checkpoint not flushed atomically	extend dedup TTL; flush checkpoint only after batch fully processes
Webhook endpoint returning 5xx for valid events	endpoint capacity or bug	Guidewire retries with backoff; eventually goes to DLQ; investigate the endpoint
Same messageId showing different payloads in DLQ	producer bug — messageId is supposed to be unique per message	escalate to Guidewire support / config team; consumer cannot fix this

For deeper coverage (Kafka partitioning strategies, exactly-once semantics across boundaries, schema evolution for event payloads, multi-tenant event fan-out), see implementation guide and API reference.

See Also

• guidewire-install-auth — auth between Guidewire and the messaging destination if it requires bearer tokens
• guidewire-core-workflow-a — the bind/issue/renewal events this skill consumes are emitted by that workflow
• guidewire-core-workflow-b — the FNOL/reserve/payment events this skill consumes
• guidewire-observability-and-incident-response — queue-depth and saturation alerts that drive this skill's back-pressure response

Resources

• Guidewire Messaging configuration documentation
• AWS SQS — at-least-once delivery semantics
• Idempotent consumer pattern
• Event-driven architecture — back-pressure