Skip to main content

Outbound webhooks

Nebula POSTs structured events to your endpoint as state changes.

End-to-end

  1. Add an endpoint at /settings/webhooks. Save the secret.
  2. Implement the receiver: parse the body, verify the signature,

process or queue the event.

  1. Return 2xx. Anything else triggers retry.

Event envelope

{
  "type": "item.transitioned",
  "occurredAt": "2026-05-06T17:00:00Z",
  "data": { "itemId": "...", "from": "PROPOSED", "to": "ACCEPTED" }
}

Idempotency

Each delivery has a unique X-Nebula-Delivery-Id. If you've seen

this id before, skip processing and return 200. We retry on

transient failure (1xx, 3xx, 4xx) but never on 4xx other than 429.

Common patterns

  • Mirror to your CRM: opportunity.* events drive the deal record
  • Update an external accounting system on payment_claim.certified
  • Send Slack messages on item.transitioned for the owning org

Cross links

  • /docs/api/webhooks: setup and signing
  • /docs/api/errors: error codes Nebula returns to you