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
http:// or https://; loopback and internal-network hosts are rejected at create time.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_nameis denormalised at delivery time so you can render "Nick added an expense" without a follow-up API call;user_idis the stable canonical id. It's a snapshot: renaming later doesn't rewrite past deliveries.{ "kind": "system", "source": "..." }is an automated source.sourcenames the subsystem (e.g.aerodatabox_webhookfor a live flight-status update). Filter onactor.kindto separate manual edits from automated changes, or onactor.sourceto 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:1for 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 indata.kind. Live flight-status updates surface here astripitem.updatedwithactor.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.sharedfires 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_removedfor 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.parsedfires when a forwarded booking confirmation completes the parse pipeline.data.statusis one ofok/partial/failed;data.trip_ids_touchedlists 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.