Webhooks¶

Subscribe to events on a bucket and Nimbus will POST a payload to your endpoint whenever they occur.

Supported events¶

record.created
record.updated
record.deleted
bucket.archived

Registering a webhook¶

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

Payload shape¶

record.created payload

{
  "event": "record.created",
  "bucket": "my-first-bucket",
  "record": {
    "name": "hello-world",
    "value": 42
  },
  "timestamp": "2026-06-18T12:00:00Z"
}

Verifying signatures¶

Every webhook request includes an X-Nimbus-Signature header: an HMAC-SHA256 hash of the raw request body, signed with your webhook secret.

import hashlib
import hmac

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

Warning

Always verify signatures before processing a webhook payload to confirm it actually came from Nimbus.