Webhooks

Gooclaim pushes webhooks to your configured URL whenever a workflow transitions state. Use webhooks to keep your CMS in sync, trigger downstream automations, or feed your own dashboards.

How webhooks work

Gooclaim Outbound Engine  ──HTTPS POST──▶  https://yourcms.example.com/gooclaim/webhook
                                            │
                                            ▼
                              Your endpoint returns 200 OK
                              within 5 seconds, or Gooclaim retries.

Webhooks are signed with HMAC-SHA256 so you can verify they really came from Gooclaim.

Setup

You configure the webhook URL once per tenant via the Console UI (or via the Tenant Config API if you have admin scope). You also receive a shared signing secret at configuration time — store it somewhere safe.

Event envelope

Every webhook payload uses the same envelope:

1
{
2
  "event_id": "evt_01HXYZ...",
3
  "event_type": "workflow.completed",
4
  "tenant_id": "tnt_xyz",
5
  "occurred_at": "2026-05-20T10:14:25Z",
6
  "data": {
7
    "workflow_id": "wf_abc123",
8
    "workflow_type": "claim-status",
9
    "claim_id_hash": "sha256:..."
10
  }
11
}

Headers:

Event catalog

More events are added in v1.1. Subscribe to specific event types via the Console; the full event-type list is also queryable via the API.

Signature verification

Always verify the signature before trusting the payload. Pseudo-code:

1
import hmac
2
import hashlib
3
4
def verify(body: bytes, signature: str, secret: str, max_age_seconds: int = 300) -> bool:
5
    expected = hmac.new(
6
        secret.encode(),
7
        body,
8
        hashlib.sha256,
9
    ).hexdigest()
10
    return hmac.compare_digest(expected, signature)

Reject the webhook if:

• the signature does not match
• X-Gooclaim-Timestamp is older than 5 minutes (replay protection)
• you have already processed this X-Gooclaim-Idempotency-Key

Retries

Gooclaim retries failed deliveries with exponential backoff:

After the final attempt, the event is moved to a dead-letter queue. You can replay dead-lettered events from the Portal.

A delivery is considered successful if your endpoint responds with 2xx within 5 seconds. 3xx, 4xx, 5xx, and timeouts all count as failures.

Idempotency

Always treat webhooks as at-least-once delivery. Use the X-Gooclaim-Idempotency-Key header to dedupe — store it for at least 7 days and reject duplicates.

Testing webhooks locally

For local development, expose your endpoint via ngrok or cloudflared and configure the public URL in your tenant settings. Gooclaim retries on TLS failures, so use a real HTTPS tunnel — localhost will not work.

Next: explore the full API

Head to the API Reference for the complete endpoint catalog.