Webhooks

Nebula calls your endpoint with structured events as state changes.

Setup

Add an endpoint at /settings/webhooks. The endpoint receives a

POST with a JSON body and an X-Nebula-Signature header.

Signing

The signature is HMAC-SHA256(body, secret). Verify with:

const expected = crypto.createHmac("sha256", secret).update(body).digest("hex")
const ok = expected === request.headers["x-nebula-signature"]

Reject if not equal.

Retry behaviour

Failed deliveries (non-2xx) retry with backoff:

30s, 2min, 10min, 1h, 6h. After 5 attempts the delivery is marked

DEAD; admin investigates.

Event types

• item.transitioned
• anchor.confirmed
• marketplace.opportunity.awarded
• eot.assessed
• defect.raised
• payment_claim.certified
• subscription.updated

Each event has the same envelope: { type, occurredAt, data }. The

data shape is event-specific; see the per-event reference.

Cross links

• /docs/integrations/outbound-webhooks: end-to-end integration
• /docs/api/errors: error codes returned to your endpoint