Webhooks Reference

Webhooks send HTTP POST requests to your endpoint when events occur in Umbrella, so you do not need to poll the API for changes.

Setup

Go to Dashboard > Settings > Integrations > Webhooks
Click Add Webhook Endpoint
Enter your HTTPS endpoint URL
Select the events you want to receive
Save and store the signing secret (shown only once)

Your endpoint must accept POST requests, return a 2xx status within 30 seconds, and accept application/json.

Event types

Policy events

Event	Description
`policy.created`	Customer purchased a warranty
`policy.activated`	Policy status changed to active
`policy.expired`	Policy reached its end date
`policy.cancelled`	Policy cancelled (refund or merchant action)
`policy.voided`	Policy voided (order cancellation or chargeback)

Claim events

Event	Description
`claim.submitted`	Customer submitted a claim
`claim.approved`	Merchant approved a claim
`claim.denied`	Merchant denied a claim
`claim.resolved`	Claim fully resolved
`claim.evidence_uploaded`	Evidence attached to a claim

Registration events

Event	Description
`registration.submitted`	Product registration submitted
`registration.approved`	Registration approved
`registration.denied`	Registration denied

Warranty events

Event	Description
`warranty.created`	New warranty plan created
`warranty.updated`	Warranty plan modified
`warranty.activated`	Warranty plan activated
`warranty.deactivated`	Warranty plan deactivated

Payload structure

Every webhook follows this envelope:

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "claim.submitted",
  "timestamp": "2025-03-15T14:30:00.000Z",
  "apiVersion": "1.3.9",
  "orgId": "org_xyz789",
  "data": { ... }
}

id — unique event ID (use for deduplication)
type — event type
timestamp — when the event occurred
data — event-specific payload containing the relevant resource details (policy, claim, registration, etc.)

Signature verification

Every request includes an X-Umbrella-Signature header with an HMAC-SHA256 hash of the request body. Verify this before processing events.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry policy

Failed deliveries (non-2xx, timeout, connection error) are retried with exponential backoff:

Attempt	Delay
2nd	1 minute
3rd	5 minutes
4th	30 minutes
5th	2 hours
6th	6 hours
7th (final)	12 hours

After 7 failed attempts, the delivery is marked as failed. A 410 Gone response permanently disables the endpoint.

Testing

Go to Dashboard > Settings > Integrations > Webhooks
Click your endpoint, then Send Test Event
Select an event type and review the delivery result

The webhook detail page also shows a log of recent deliveries with status codes and timing.

Note Return 200 immediately and process events asynchronously to avoid timeouts. Use the event id to deduplicate, since retries may deliver the same event more than once.

Authentication — API security and credentials
Claims API — Claim management endpoints
Policies API — Policy management endpoints