Skip to content

Tutorial: Sync Data with Webhooks

This tutorial keeps a local search index up to date by reacting to record.created, record.updated, and record.deleted events.

1. Register the webhook

nimbus webhooks create \
  --url https://search.example.com/webhooks/nimbus \
  --events record.created,record.updated,record.deleted

2. Handle each event type

def handle_event(event: dict) -> None:
    match event["event"]:
        case "record.created" | "record.updated":
            index.upsert(event["record"])
        case "record.deleted":
            index.remove(event["record"]["name"])

3. Backfill existing data

Webhooks only cover events going forward. To seed the index with existing records, run a one-time export and index every record before relying on live events.

nimbus exports create --bucket my-first-bucket --format ndjson

4. Handle redelivery

Nimbus retries failed webhook deliveries with backoff. Make your handler idempotent — upserting the same record twice should be a no-op, not an error.

Use the event timestamp to detect stale updates

If your handler can receive events out of order, compare event.timestamp against the last-indexed timestamp and skip updates that are older than what you already have.