Developer

Webhooks

Webhooks push events from a Constellations account to a URL you control, so external automations can react in real time: n8n, Pipedream, Zapier, Home Assistant, anything that can receive an HTTP POST. Common uses include piping new expenses into a spreadsheet, kicking off a "travelling now" routine when a trip starts, or relaying flight-status changes to a phone.

The full management UI lives at Settings → Custom connections, alongside API tokens and the MCP address.

How it works

Register a URL, tick the events you want, and Constellations POSTs a signed JSON payload to that URL when one of those events happens. Endpoints are per-user: you receive events on your own activity and on shared items you can see. Items you've kept private fire only on your own endpoints.

Adding an endpoint

Adding an endpoint
YouIn Settings → Custom connections, click Add endpoint.
YouGive it a recognisable name, paste the receiver URL, and tick the events to push to it. URLs must be http:// or https://; loopback and internal-network hosts are rejected at create time.
YouSave, then copy the signing secret into your receiver's HMAC verification step. It's shown once; the listing UI shows only the first 12 characters afterwards, as a fingerprint.
AutomaticMatching events are POSTed to the URL as signed JSON from then on.

The payload

Every delivery is a JSON POST with this envelope:

{
  "id": "<unique delivery uuid>",
  "type": "expense.created",
  "api_version": "2026-05",
  "created_at": "2026-05-25T07:54:31Z",
  "actor": { "kind": "user", "user_id": "...", "display_name": "Nick" },
  "data": { /* event-specific */ }
}

data carries only what the endpoint's owner can see in the app. A booking's title in a delivery is the title shown to that person, so two people's endpoints can receive the same event with different titles.

The id is your idempotency key. If the same delivery arrives twice, you can skip the duplicate by tracking ids you've already handled.

The actor tells you who triggered the event:

  • { "kind": "user", "user_id": "...", "display_name": "..." } is a signed-in user acting through the app or API. display_name is denormalised at delivery time so you can render "Nick added an expense" without a follow-up API call; user_id is the stable canonical id. It's a snapshot: renaming later doesn't rewrite past deliveries.
  • { "kind": "system", "source": "..." } is an automated source. source names the subsystem (e.g. aerodatabox_webhook for a live flight-status update). Filter on actor.kind to separate manual edits from automated changes, or on actor.source to single out one automated subsystem.

Signature verification

Every delivery is signed with HMAC-SHA256 over <timestamp>.<rawBody>, keyed by your endpoint's secret. Two headers carry the material:

  • X-Constellations-Timestamp: unix seconds at delivery time.
  • X-Constellations-Signature: sha256=<hex> of the HMAC.

Three other headers are worth knowing:

  • X-Constellations-Event: the event type.
  • X-Constellations-Delivery: the delivery id.
  • X-Constellations-Attempt: 1 for the first try, incremented on each retry.

Outbound requests also carry User-Agent: Constellations-Webhook/1.0 (https://constellations.li) if your receiver wants a canonical string to allowlist on.

The timestamp is folded into the signed material AND surfaced separately so receivers can reject stale payloads. A captured body replayed a day later still has a valid HMAC, but the timestamp will be far outside the tolerance window and the verify step rejects it. Five minutes is the convention.

Example verification in Node.js / n8n function nodes:

const crypto = require("crypto");
const TOLERANCE_SECONDS = 5 * 60;

const ts = req.headers["x-constellations-timestamp"];
const provided = req.headers["x-constellations-signature"];

if (Math.abs(Math.floor(Date.now() / 1000) - Number(ts)) > TOLERANCE_SECONDS) {
  throw new Error("timestamp outside tolerance: possible replay");
}

const expected =
  "sha256=" +
  crypto
    .createHmac("sha256", SECRET)
    .update(`${ts}.${rawBody}`, "utf8")
    .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided))) {
  throw new Error("invalid signature");
}

Verify against the raw body as received. Re-stringifying the parsed JSON changes whitespace and key order, and the signature check will fail.

Receipts and attachments

Two parallel surfaces, same mechanism. Expense receipts ride along on expense.created / expense.updated. Trip-item attachments (booking confirmations, hotel vouchers, passport scans linked to a travel, stay, or event item) have their own attachment.added / attachment.updated / attachment.deleted events.

Expense events carry a receipt object on data:

"receipt": {
  "url": "https://constellations.li/api/expense-assets/<id>?wat=...",
  "label": "Sushi place.pdf",
  "source": "constellations",
  "expires_at_ms": 1748252071734
}

Attachment events carry a file object on data:

"file": {
  "attachment_id": "...",
  "url": "https://constellations.li/api/assets/<id>?wat=...",
  "label": "Boarding pass.pdf",
  "source": "constellations",
  "notes": null,
  "visibility": "private",
  "expires_at_ms": 1748252071734
}

Fetch the url directly. The link is short-lived (about 40 minutes from delivery) and scoped to that one file. Processed promptly, the link works; queued and replayed an hour later, it returns 410 Gone. Check expires_at_ms (unix milliseconds) before fetching.

For files that come from Google Drive, OneDrive, or Dropbox, the url is the raw provider URL and expires_at_ms is null. Authenticate to the provider yourself when fetching those.

expense.deleted and attachment.deleted events omit url but keep the metadata (label, source) so you can record what was attached.

Retries

A delivery is considered successful when your receiver returns HTTP 2xx. Network errors, timeouts, TLS failures, 5xx, and transient 4xx (408, 429) all mark the attempt as failed and trigger a retry.

Terminal 4xx (400, 404, 410, and 422) short-circuits to dead immediately, with no further retries. These status codes mean the payload itself is rejected, so retrying gains nothing. If your receiver wants the event redelivered after a fix, use the manual retry button in the delivery log.

Retriable failures follow exponential backoff: 1, 2, 4, 8, 16, 32 minutes between attempts, capped at 6 attempts total, so the last automatic retry fires about 31 minutes after the first. After that, the row is marked dead and can be re-fired manually.

Retry-After is honored. If your receiver returns 429 Too Many Requests (or any 4xx) with a Retry-After: <seconds> header, the next attempt waits at least that long instead of the default exponential delay. Values above one hour are ignored as likely misconfiguration.

Each attempt has a 15-second HTTP timeout. Slow receivers should respond 200 OK immediately and queue the actual work asynchronously.

If an endpoint racks up 20 consecutive failures across all events, it's auto-disabled and a signal is sent (Webhook endpoint auto-disabled, email + in-app by default) naming the endpoint and why. Re-enable from the endpoint's edit dialog; that resets the failure streak.

Testing without a real receiver

Each endpoint has a Send test ping button that fires a ping-type event immediately. The body is minimal, but the signature, headers, and delivery row all behave exactly like a real event. Aim it at webhook.site or Pipedream to inspect what arrives, then swap to your real receiver once the shape is right.

If the test ping doesn't arrive, the most common cause is the receiver URL being unreachable from the public internet; try loading it in a normal browser first.

A second pitfall worth checking: the receiver URL must respond directly, not redirect through a sign-in page. Webhook delivery treats a redirect to anything that looks like authentication as a failed delivery. A URL behind your app's own login won't work even if the page loads fine in a browser (the browser is signed in; the webhook isn't).

Delivery log

Every delivery (success, failure, dead, retrying) shows up on Settings → Custom connections. The log includes the response status, the first 512 chars of the body the receiver returned, the error message if any, and how many attempts it took. Failed and dead rows have a manual retry button.

The log keeps two weeks of deliveries by default; older rows are pruned automatically. Endpoint definitions and their event subscriptions are kept until you remove them; only delivery history rotates.

Currently available events

The catalogue grows over time. The current set:

  • Lifecycle: ping
  • Expenses: expense.created, expense.updated, expense.deleted
  • Trips: trip.created, trip.renamed
  • Trip items: tripitem.added, tripitem.updated, tripitem.deleted. Kind-generic; the specific kind (travel, stay, event, document) lives in data.kind. Live flight-status updates surface here as tripitem.updated with actor.kind == "system".
  • Files: attachment.added, attachment.updated, attachment.deleted. Files linked to a trip item. The payload carries a signed ?wat= URL for Constellations-hosted files, or the provider URL passed through for Drive / OneDrive / Dropbox.
  • Trip sharing: trip.shared fires when a participant is added to a trip. The new participant is in the audience, so receivers on their endpoints can react too.
  • Constellations: constellation.member_added, constellation.member_removed for group membership changes. The removed or leaving user is included in the pre-delete audience so they receive the removal event on their own endpoints.
  • Friends: friend.request_received (recipient only), friend.request_accepted (both parties).
  • Inbound mail: inbound_email.parsed fires when a forwarded booking confirmation completes the parse pipeline. data.status is one of ok / partial / failed; data.trip_ids_touched lists any trips that were created or updated. Useful for monitoring that the forward pipeline is working.

Subscriptions are picked per endpoint, so one endpoint can listen for expenses (pipe to a spreadsheet) and another for flight updates (push to a phone via Pushover), each with its own secret.

Rotating the secret

If the endpoint secret may have leaked, open the endpoint's edit dialog and click Regenerate secret. The previous secret stops signing deliveries immediately, and the next event arrives signed with the new value. Update your receiver before its next delivery, or the signature check there will fail.

The secret is stored once and shown once; keep your copy somewhere safe. The listing UI shows the first 12 characters as a fingerprint for matching your local copy.