Webhooks

Webhooks allow your server to receive HTTP POST notifications when documents change.

Setting Up Webhooks

Via Dashboard

1. Go to the project Dashboard
2. Click Create Webhook
3. Enter your endpoint URL
4. Select events to subscribe to
5. Save

Via API

curl -X POST https://api.example.org/v1/webhooks \
  -H "Authorization: Bearer cs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/cloudsync",
    "events": ["document.changed", "document.deleted", "sync.conflict"],
    "secret": "whsec_your_signing_secret"
  }'

Webhook Events

Event	Description
document.changed	A document field was created, updated, or deleted
document.deleted	An entire document was deleted
document.created	A new document was created
sync.conflict	A conflict was detected and resolved
sync.completed	A full sync cycle completed
connection.lost	A client disconnected unexpectedly

Payload Format

{
  "id": "evt_1a2b3c4d5e6f",
  "type": "document.changed",
  "timestamp": "2025-01-12T10:30:00.000Z",
  "data": {
    "document_key": "user:12345:preferences",
    "changes": [
      {
        "field": "theme",
        "old_value": "light",
        "new_value": "dark",
        "origin": "node_abc123"
      }
    ],
    "revision": 42
  }
}

Signature Verification

Every webhook request includes a X-CloudSync-Signature header. Always verify this signature.

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Using the SDK helper

from cloudsync.webhooks import verify_signature

is_valid = verify_signature(
    payload=request.body,
    signature=request.headers["X-CloudSync-Signature"],
    secret="whsec_your_signing_secret"
)

Retry Policy

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

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed attempts, the webhook is marked as disabled and an email notification is sent.

Respond quickly

Your webhook endpoint should return 200 OK within 5 seconds. Process events asynchronously if needed.

---

Next: Rate Limiting →