Webhooks | Umbrella Docs

Webhook Configuration

Dashboard → Settings → Webhooks

Umbrella sends webhook notifications to your external systems when warranty events occur. Use webhooks to integrate with your CRM, support desk, analytics, or backend services.

Note This covers outbound webhooks from Umbrella. For Shopify-to-Umbrella sync, see Shopify Product Sync.

Event Types

Policy Events

Event	Description
`policy.created`	Warranty policy created (order completed with warranty)
`policy.activated`	Policy activated (payment confirmed)
`policy.expired`	Policy reached its end date
`policy.cancelled`	Policy cancelled (refund or order cancellation)
`policy.updated`	Policy updated (status or metadata change)

Claim Events

Event	Description
`claim.created`	New claim filed
`claim.updated`	Claim status changed
`claim.approved`	Claim approved
`claim.denied`	Claim denied
`claim.resolved`	Claim resolved (replacement shipped or refund issued)

Order Events

Event	Description
`order.warranty_attached`	Warranty attached to an order line item
`order.warranty_removed`	Warranty removed from an order
`order.post_purchase_completed`	Post-purchase warranty upsell completed

Customer Events

Event	Description
`customer.policy_assigned`	Policy assigned to a customer
`customer.claim_filed`	Customer filed a claim

Payload Format

All payloads follow this structure:

{
  "id": "wh_evt_abc123def456",
  "event": "policy.created",
  "timestamp": "2026-03-17T14:30:00.000Z",
  "version": "1.0",
  "data": { ... },
  "metadata": {
    "orgId": "org_abc",
    "integrationPlatform": "shopify",
    "shopDomain": "my-store.myshopify.com"
  }
}

id — unique event ID (use for deduplication)
event — event type
data — event-specific payload with resource details
metadata — organization and integration context

Signature Verification

All webhooks include an X-Umbrella-Signature header (HMAC-SHA256 of the request body). Always verify this before processing. See Webhooks Reference for verification code examples.

Important Use constant-time comparison (e.g., crypto.timingSafeEqual()) to prevent timing attacks.

Retry Policy

Failed deliveries (non-2xx response or timeout) are retried with exponential backoff:

Attempt	Delay
1st retry	30 seconds
2nd retry	2 minutes
3rd retry	10 minutes
4th retry	1 hour
5th retry	6 hours
Final retry	24 hours

Your endpoint must respond with 200, 201, or 202 within 30 seconds. Respond immediately and process asynchronously to avoid timeouts.

Setting Up an Endpoint

Go to Dashboard → Settings → Webhooks
Click Add Endpoint
Enter your HTTPS endpoint URL and select events
Copy and securely store the signing secret (shown only once)
Test using Send Test Event on the endpoint detail page

Webhook Logs

Dashboard → Settings → Webhooks → Logs

The logs page shows delivery history per endpoint: event type, status (success/failed/retried), response code, response time, timestamp, and attempt count.

Shopify Product Sync — Shopify webhook synchronization
Shopify Integration — Overall Shopify connection
Widget Configuration — Widget display settings