API Webhooks

Webhooks

Webhooks notify your application in real time when events occur in myumbrella.ai, like a new claim being filed or a contract being activated.

Setting Up Webhooks

1. Go to Settings → Webhooks → Add Endpoint
2. Enter your endpoint URL (must be HTTPS)
3. Select the events you want to receive
4. Save and copy the signing secret

Event Types

Event	Trigger
contract.created	New warranty contract activated
contract.cancelled	Contract cancelled or refunded
claim.submitted	New claim filed
claim.approved	Claim approved for resolution
claim.denied	Claim denied
claim.resolved	Claim resolution completed
plan.updated	Warranty plan configuration changed

Payload Format

{
  "id": "evt_abc123",
  "type": "claim.submitted",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "claim_id": "clm_xyz789",
    "contract_id": "ctr_def456",
    "customer_email": "jane@example.com",
    "issue_type": "accidental_damage",
    "amount": 299.99
  }
}

Verifying Signatures

Every webhook includes an X-Umbrella-Signature header. Verify it to ensure authenticity:

const crypto = require('crypto');

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

Retry Policy

Failed deliveries (non-2xx response) are retried up to 5 times with exponential backoff: 1 min, 5 min, 30 min, 2 hours, 24 hours.