Docs/Guides/Webhooks

Webhooks

Get notified over HTTP instead of polling. Webhook URLs must use https://.

Event types

Event	Fires when
`database.created`	A database finishes provisioning successfully.
`database.failed`	A database provisioning job fails.
`backup.completed`	A backup finishes successfully.
`backup.failed`	A backup job fails.
`restore.completed`	A restore-to-new-database finishes successfully.
`invoice.paid`	An invoice is marked paid.

Create a webhook

curl -X POST https://api.astrabase.app/api/v1/organizations/$ORG_ID/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/astrabase", "event_types": ["database.created", "backup.completed"]}'

The response includes a secret — like an API key, it's shown once. Save it; GET .../webhooks never returns it again.

Verifying deliveries

Every delivery is a real signed POST with:

X-Eminidatabase-Event: the event type, e.g. database.created
X-Eminidatabase-Signature: sha256=<hex hmac-sha256 of the exact request body>

import hashlib
import hmac

expected = hmac.new(secret.encode(), body_bytes, hashlib.sha256).hexdigest()
assert hmac.compare_digest(expected, received_signature.removeprefix("sha256="))

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", secret).update(bodyBytes).digest("hex");
const received = receivedSignature.replace("sha256=", "");
const isValid = timingSafeEqual(Buffer.from(expected), Buffer.from(received));

Delivery history

curl https://api.astrabase.app/api/v1/organizations/$ORG_ID/webhooks/$WEBHOOK_ID/deliveries -H "Authorization: Bearer $TOKEN"

Shows every attempt with status and response, useful for debugging an endpoint that isn't receiving events correctly.

Deleting

curl -X DELETE https://api.astrabase.app/api/v1/organizations/$ORG_ID/webhooks/$WEBHOOK_ID -H "Authorization: Bearer $TOKEN"

Was this page helpful?

Previous← API keys NextBilling & plans →