Skip to main content

Data Retention

Kula retains webhook delivery logs and related data for a limited time. Understand these policies to ensure you capture and archive the data you need.

Delivery Logs​

Webhook delivery logs are retained for 30 days. After this period, logs are automatically deleted.

Data TypeRetention Period
Delivery attempts30 days
Response status codes30 days
Response times30 days
Error messages30 days

Viewing Delivery Logs​

Query recent deliveries via the API:

curl "https://api.kula.ai/v1/webhooks/{id}/deliveries" \
  -H "Authorization: Bearer your_api_token_here"

Response includes delivery status and timing:

{
  "data": [
    {
      "id": "del_abc123",
      "event_id": "evt_xyz789",
      "event_type": "application.created",
      "status": "success",
      "response_code": 200,
      "response_time_ms": 145,
      "attempted_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 156,
    "page": 1,
    "limit": 20
  }
}

Archiving Best Practices​

Since delivery logs expire after 30 days, implement archiving if you need long-term records:

Store Webhook Payloads​

Save incoming webhooks to your database:

app.post('/webhooks/kula', async (req, res) => {
  // Verify signature first
  if (!verifyWebhook(req)) {
    return res.status(401).send('Invalid signature');
  }

  // Archive the payload
  await db.webhookArchive.insert({
    eventId: req.body.event_id,
    eventType: req.body.event_type,
    payload: JSON.stringify(req.body),
    receivedAt: new Date(),
    headers: {
      signature: req.headers['x-kula-signature'],
      timestamp: req.headers['x-kula-timestamp']
    }
  });

  res.status(200).send('OK');
});

Export Delivery Logs Periodically​

Create a scheduled job to export logs before they expire:

// Run daily to export delivery logs
async function exportDeliveryLogs() {
  const webhooks = await fetchWebhooks();

  for (const webhook of webhooks) {
    const deliveries = await fetchDeliveries(webhook.id);

    await archiveDeliveries({
      webhookId: webhook.id,
      deliveries,
      exportedAt: new Date()
    });
  }
}

What's Not Retained​

The following data is not stored in delivery logs:

  • Full request/response bodies (store these yourself)
  • Payload contents after delivery
  • Custom headers you send in responses

Compliance Considerations​

If your organization has data retention requirements:

  • Archive webhooks immediately upon receipt
  • Include timestamps and event IDs for audit trails
  • Store signature headers for verification records
  • Document your retention policies