15 min read

Webhook Events

Receive real-time notifications for policy and claim events.

Overview

Webhooks allow you to receive real-time notifications when events occur in your CoverKit account. Instead of polling the API, webhooks push data to your server automatically.

Setting Up Webhooks

const webhook = await coverkit.webhooks.create({
  url: 'https://your-server.com/webhooks/coverkit',
  events: [
    'quote.created',
    'policy.created',
    'policy.cancelled',
    'claim.submitted',
    'claim.approved',
    'claim.paid',
  ],
});

// Save the webhook secret for signature verification
console.log('Webhook Secret:', webhook.secret);

Event Types

Quote Events

quote.created - New quote generated

quote.expired - Quote expired without binding

Policy Events

policy.created - Policy bound and active

policy.renewed - Policy renewed

policy.cancelled - Policy cancelled

policy.expired - Policy term ended

Claim Events

claim.submitted - New claim filed

claim.approved - Claim approved

claim.denied - Claim denied

claim.paid - Payout completed

Webhook Payload

{
  "id": "evt_abc123",
  "type": "policy.created",
  "createdAt": "2024-12-20T12:00:00Z",
  "data": {
    "id": "policy_xyz789",
    "quoteId": "quote_abc123",
    "status": "active",
    "premium": 299,
    "customer": {
      "email": "customer@example.com"
    }
  }
}

Signature Verification

Always verify webhook signatures to ensure requests come from CoverKit.

Verifying Signatures

// Node.js/Express example
app.post('/webhooks/coverkit', (req, res) => {
  const signature = req.headers['coverkit-signature'];
  const payload = req.body;

  try {
    const event = coverkit.webhooks.verify(
      payload,
      signature,
      process.env.COVERKIT_WEBHOOK_SECRET
    );

    // Handle the event
    switch (event.type) {
      case 'policy.created':
        handlePolicyCreated(event.data);
        break;
      case 'claim.approved':
        handleClaimApproved(event.data);
        break;
    }

    res.status(200).json({ received: true });
  } catch (err) {
    res.status(400).json({ error: 'Invalid signature' });
  }
});

Retry Policy

CoverKit retries failed webhook deliveries with exponential backoff:

1st retry: 1 minute
2nd retry: 5 minutes
3rd retry: 30 minutes
4th retry: 2 hours
5th retry: 24 hours

After 5 failed attempts, the webhook is marked as failed and no further retries are attempted.