Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.
TypeScript i18nextnext-authnextjspostgresqlprismareact-emailt3-stacktailwindcsstrpcturborepotypescriptzod
π Document webhooks: guide, one page per event, and the OpenAPI webhooks section (#3340)
Luke Vellad17eb780edfc
diff --git a/apps/docs/api-reference/authentication.mdx b/apps/docs/api-reference/authentication.mdxindex d77bf7b59..e5084cd3f 100644--- a/apps/docs/api-reference/authentication.mdx+++ b/apps/docs/api-reference/authentication.mdx@@ -1,5 +1,6 @@---title: "Authentication"+icon: "key"description: "Authenticate every request with a space API key."---diff --git a/apps/docs/api-reference/changelog.mdx b/apps/docs/api-reference/changelog.mdxindex 61f4e4200..d7be472ae 100644--- a/apps/docs/api-reference/changelog.mdx+++ b/apps/docs/api-reference/changelog.mdx@@ -1,5 +1,6 @@---title: "Changelog"+icon: "clock-rotate-left"description: "Changes to the API, newest first."---@@ -8,6 +9,12 @@ description: "Changes to the API, newest first."- Participants now carry `availability`: one `{ start, end, allDay, modifiers }` span per option they can make, in start order, on both the list and the single-participant endpoint. A span matches an option of the poll by its time; `end` is exclusive; `ifNeedBe` is a modifier.</Update>+<Update label="2026-09-20">+Webhooks, in beta. A space can register up to five HTTPS endpoints and receive signed, retried deliveries for nine poll and participant events. The event list and payloads may still change, and more events will be added. See [Webhooks](/api-reference/webhooks).++The poll and participant resources are unchanged.+</Update>+<Update label="v1">Initial stable release under `/v1`.@@ -16,5 +23,4 @@ Initial stable release under `/v1`.- Bearer authentication with space API keys- Per space rate limits with `RateLimit-*` headers-Webhooks for poll events are planned. There is no date yet.</Update>diff --git a/apps/docs/api-reference/errors.mdx b/apps/docs/api-reference/errors.mdxindex 06bbc52d6..3257a1780 100644--- a/apps/docs/api-reference/errors.mdx+++ b/apps/docs/api-reference/errors.mdx@@ -1,5 +1,6 @@---title: "Errors"+icon: "triangle-exclamation"description: "The error envelope and every code the API returns."---diff --git a/apps/docs/api-reference/introduction.mdx b/apps/docs/api-reference/introduction.mdxindex 461842465..3b6495129 100644--- a/apps/docs/api-reference/introduction.mdx+++ b/apps/docs/api-reference/introduction.mdx@@ -1,13 +1,12 @@---title: "Introduction"+icon: "house"description: "Create and manage scheduling polls from your own systems."----The Rallly API lets you create polls, read their options, results and participants, and delete them from your own tools. Every request is scoped to one space: the API key identifies the space, and every poll you create or read belongs to it.+The Rallly API lets you create polls, read their options, results and participants, and delete them from your own tools. Every request is scoped to one space: the API key identifies the space, and every poll you create or read belongs to it. [Webhooks](/api-reference/webhooks) tell your systems when a poll or a response changes, so you never have to poll for results.-## Availability--The API is available for spaces on a Pro plan of the cloud hosted version, at `https://api.rallly.co`. It is not available on self-hosted instances.+<Note>The API requires a Pro plan.</Note>## Getting a key@@ -19,6 +18,8 @@ Only the space owner can create API keys, from **Settings β API keys**. See [Ahttps://api.rallly.co/v1```+The API is served by the cloud hosted version only; self-hosted instances do not have it.+`v1` is stable. Additive changes such as new endpoints or new optional fields may land at any time; breaking changes only arrive under a new version prefix. The [changelog](/api-reference/changelog) records both.## Conventionsdiff --git a/apps/docs/api-reference/migrating-from-the-private-api.mdx b/apps/docs/api-reference/migrating-from-the-private-api.mdxindex dc15129a4..5fe5ead17 100644--- a/apps/docs/api-reference/migrating-from-the-private-api.mdx+++ b/apps/docs/api-reference/migrating-from-the-private-api.mdx@@ -1,5 +1,6 @@---title: "Migrating from the private API"+icon: "arrow-right-arrow-left"description: "Move an integration from /api/private to /v1, endpoint by endpoint."---diff --git a/apps/docs/api-reference/rate-limits.mdx b/apps/docs/api-reference/rate-limits.mdxindex b8885a61d..7313be60e 100644--- a/apps/docs/api-reference/rate-limits.mdx+++ b/apps/docs/api-reference/rate-limits.mdx@@ -1,5 +1,6 @@---title: "Rate limits"+icon: "gauge-high"description: "Per space request limits and how to back off."---diff --git a/apps/docs/api-reference/webhooks.mdx b/apps/docs/api-reference/webhooks.mdxnew file mode 100644index 000000000..c47595bfe--- /dev/null+++ b/apps/docs/api-reference/webhooks.mdx@@ -0,0 +1,43 @@+---+title: "Overview"+sidebarTitle: "Overview"+icon: "webhook"+description: "Get an HTTPS request when a poll or a response changes."+---++Webhooks tell your own systems about poll and participant changes as they happen, so an integration never has to poll the API for results. Each endpoint you register receives a signed `POST` for every event it subscribes to.++<Note>Webhooks require a Pro plan.</Note>++<Warning>+ Webhooks are in beta. The event list and payloads may still change while we settle the design, and more events will be added. Changes that could break a receiver will arrive under a new payload version.+</Warning>++## Adding an endpoint++1. As the space owner, open **Settings β Webhooks** and choose **Add webhook**.+2. Enter the URL. It must be `https`, on a public host, with no credentials in it.+3. Pick the events to receive. Every event is selected by default; you can change the selection later.+4. Copy the signing secret. It is shown once. If you lose it, delete the endpoint and add it again.++A space can have up to five endpoints. A new endpoint starts receiving events from the moment it is created; history is never replayed.++## What an event carries++An event says what happened and to which poll or participant. It references both by id and carries only the facts that belong to the event itself: the reason a poll closed, the time it was scheduled for. It does not carry the poll's title, options or settings, or the participant's details. Fetch the API when you need them; the fetch returns the current state, where a snapshot in the event would already be stale by the time a retry lands.++See [Events](/api-reference/webhooks/events) for the envelope, the headers and every event with its payload.++## Delivery++Every delivery is a `POST` with a JSON body. Respond with any `2xx` status within 10 seconds; the response body is ignored. Redirects are not followed and count as failures.++Delivery is at least once. A delivery that fails is retried with backoff after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours; after the sixth failure it is exhausted and not retried. Failed deliveries never block later ones, so a burst of events can arrive out of order: sort on `createdAt` if order matters, and deduplicate on `id`, which retries of one event share.++An endpoint that exhausts twenty deliveries in a row is disabled. Re-enable it from the settings page once the receiver is fixed; events that happened while it was disabled are not delivered.++Every request is signed. Verify the signature before acting on a body; [Security](/api-reference/webhooks/security) shows how.++## Versioning++The payload contract is dated. `version` in the body and the `X-Rallly-Webhook-Version` header carry the version a delivery was built against; today that is `2026-09-20`. Additive changes, such as new fields, new events or new modifiers, keep the version, so ignore fields you do not recognise. A change that could break a receiver arrives under a new date, and existing endpoints keep the version they were created with until you upgrade them.diff --git a/apps/docs/api-reference/webhooks/events.mdx b/apps/docs/api-reference/webhooks/events.mdxnew file mode 100644index 000000000..fa2a55faa--- /dev/null+++ b/apps/docs/api-reference/webhooks/events.mdx@@ -0,0 +1,242 @@+---+title: "Events"+icon: "bolt"+description: "The envelope every event shares, the headers on every request, and the events you can subscribe to."+---++## Envelope++Every body has the same outer shape. `data` is the only part that differs between events.++```json+{+ "version": "2026-09-20",+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "type": "poll.closed",+ "createdAt": "2025-01-12T08:30:00.000Z",+ "data": {+ "poll": { "id": "Xk3pQ9vLm2Ab" },+ "reason": "manual"+ }+}+```++| Field | Meaning |+| --- | --- |+| `version` | The payload contract the body was built against. See [Versioning](/api-reference/webhooks#versioning) |+| `id` | The event's stable id. Retries carry the same `id`; deduplicate on it |+| `type` | The event, also sent as the `X-Rallly-Event` header |+| `createdAt` | When the change happened, not when the request was sent |+| `data` | The event's payload. Each event page documents it |++Payloads are deliberately thin. An event says what happened and to which poll or participant, by id; it does not describe them. Fetch the API for the current state when you need it, and treat the event as the signal to do so.++## Headers++| Header | Value |+| --- | --- |+| `Content-Type` | `application/json` |+| `X-Rallly-Event` | The event type, the same as `type` in the body |+| `X-Rallly-Delivery` | Unique per delivery attempt |+| `X-Rallly-Webhook-Version` | The payload version, the same as `version` in the body |+| `X-Rallly-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256>`. See [Security](/api-reference/webhooks/security) |+| `User-Agent` | `Rallly-Webhooks/1.0` |++## Events++Event names are `<resource>.<transition>`, or `<resource>.<part>.<transition>` for a change to part of a resource. New events may be added without a version change; ignore types you do not recognise rather than failing on them.++Every poll event carries `data.poll`, a reference to the poll:++```json+{ "poll": { "id": "Xk3pQ9vLm2Ab" } }+```++Fetch `GET /polls/{pollId}` for the title, options, settings and current status. Events about a response add `data.participant`, a reference to the participant; fetch `GET /polls/{pollId}/participants/{participantId}` for their name, email and availability.++One event per transition. A poll that is closed, reopened and closed again produces three events, each describing the transition it records.++| Event | When |+| --- | --- |+| `poll.created` | A poll was created |+| `poll.updated` | The poll's details, options or settings changed |+| `poll.closed` | The poll stopped accepting responses |+| `poll.reopened` | A closed poll accepts responses again |+| `poll.scheduled` | The organizer picked a time |+| `poll.deleted` | The poll was deleted |+| `poll.participant.created` | Someone responded |+| `poll.participant.updated` | A participant changed their response |+| `poll.participant.deleted` | A response was removed |++### Payloads++<AccordionGroup>+ <Accordion title="poll.created">+ A poll was created, from the app or the API.++ ```json+ {+ "version": "2026-09-20",+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "type": "poll.created",+ "createdAt": "2025-01-12T08:30:00.000Z",+ "data": {+ "poll": {+ "id": "Xk3pQ9vLm2Ab"+ }+ }+ }+ ```+ </Accordion>+ <Accordion title="poll.updated">+ The poll's details, options or settings changed. The event says that something changed, not what; fetch the poll for its current state.++ ```json+ {+ "version": "2026-09-20",+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "type": "poll.updated",+ "createdAt": "2025-01-12T08:30:00.000Z",+ "data": {+ "poll": {+ "id": "Xk3pQ9vLm2Ab"+ }+ }+ }+ ```+ </Accordion>+ <Accordion title="poll.closed">+ The poll stopped accepting responses. `reason` is `manual` when the organizer closed it and `auto` when it closed because every option had passed.++ ```json+ {+ "version": "2026-09-20",+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "type": "poll.closed",+ "createdAt": "2025-01-12T08:30:00.000Z",+ "data": {+ "poll": {+ "id": "Xk3pQ9vLm2Ab"+ },+ "reason": "manual"+ }+ }+ ```+ </Accordion>+ <Accordion title="poll.reopened">+ A closed poll accepts responses again.++ ```json+ {+ "version": "2026-09-20",+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "type": "poll.reopened",+ "createdAt": "2025-01-12T08:30:00.000Z",+ "data": {+ "poll": {+ "id": "Xk3pQ9vLm2Ab"+ }+ }+ }+ ```+ </Accordion>+ <Accordion title="poll.scheduled">+ The organizer picked a time. The poll stops accepting responses, and `event` is the span that was chosen: `start` inclusive, `end` exclusive, both UTC instants. `allDay: true` means a whole calendar day, given as midnight to midnight UTC.++ ```json+ {+ "version": "2026-09-20",+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "type": "poll.scheduled",+ "createdAt": "2025-01-12T08:30:00.000Z",+ "data": {+ "poll": {+ "id": "Xk3pQ9vLm2Ab"+ },+ "event": {+ "start": "2025-01-15T09:00:00.000Z",+ "end": "2025-01-15T09:30:00.000Z",+ "allDay": false+ }+ }+ }+ ```+ </Accordion>+ <Accordion title="poll.deleted">+ The poll was deleted. `GET /polls/{pollId}` returns `404` from now on, so anything you need about it must already be stored.++ ```json+ {+ "version": "2026-09-20",+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "type": "poll.deleted",+ "createdAt": "2025-01-12T08:30:00.000Z",+ "data": {+ "poll": {+ "id": "Xk3pQ9vLm2Ab"+ }+ }+ }+ ```+ </Accordion>+ <Accordion title="poll.participant.created">+ Someone responded to the poll.++ ```json+ {+ "version": "2026-09-20",+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "type": "poll.participant.created",+ "createdAt": "2025-01-12T08:30:00.000Z",+ "data": {+ "poll": {+ "id": "Xk3pQ9vLm2Ab"+ },+ "participant": {+ "id": "cm5j2r8wb0003q9l4a1x6p0zt"+ }+ }+ }+ ```+ </Accordion>+ <Accordion title="poll.participant.updated">+ A participant changed their response or their name.++ ```json+ {+ "version": "2026-09-20",+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "type": "poll.participant.updated",+ "createdAt": "2025-01-12T08:30:00.000Z",+ "data": {+ "poll": {+ "id": "Xk3pQ9vLm2Ab"+ },+ "participant": {+ "id": "cm5j2r8wb0003q9l4a1x6p0zt"+ }+ }+ }+ ```+ </Accordion>+ <Accordion title="poll.participant.deleted">+ A response was removed, by the participant or the organizer. Fetching the participant returns `404`.++ ```json+ {+ "version": "2026-09-20",+ "id": "cm5h8x2k40000q9l4f7e2d3an",+ "type": "poll.participant.deleted",+ "createdAt": "2025-01-12T08:30:00.000Z",+ "data": {+ "poll": {+ "id": "Xk3pQ9vLm2Ab"+ },+ "participant": {+ "id": "cm5j2r8wb0003q9l4a1x6p0zt"+ }+ }+ }+ ```+ </Accordion>+</AccordionGroup>diff --git a/apps/docs/api-reference/webhooks/guides/n8n.mdx b/apps/docs/api-reference/webhooks/guides/n8n.mdxnew file mode 100644index 000000000..ea994dca3--- /dev/null+++ b/apps/docs/api-reference/webhooks/guides/n8n.mdx@@ -0,0 +1,87 @@+---+title: "Receive webhooks in n8n"+sidebarTitle: "n8n"+icon: "diagram-project"+description: "Trigger an n8n workflow from a Rallly event, verify it, and fetch the poll."+---++This guide builds a workflow that receives a Rallly event, checks that it really came from Rallly, and fetches the poll it is about. Five nodes: Webhook, Code, Switch, HTTP Request, and whatever you do with the result.++<Steps>+ <Step title="Add a Webhook node">+ Set **HTTP Method** to `POST` and **Respond** to `Immediately`. Rallly waits at most 10 seconds for a `2xx`, and responding first means a slow step later in the workflow never turns into a retry.++ Under **Options**, switch on **Raw Body**. This is the step people miss. The signature covers the request body byte for byte; without this option the node parses the JSON and hands you an object, and re-serialising that object produces different bytes and a digest that never matches. With Raw Body on, the exact bytes are kept as binary data on the item, in the property named `data`.++ Copy the node's **Production URL**.+ </Step>++ <Step title="Register the endpoint in Rallly">+ In Rallly, open **Settings β Webhooks**, choose **Add webhook**, paste the URL and pick the events you want. Copy the signing secret: it is shown once.++ In n8n, store the secret where the workflow can read it without it appearing in the workflow JSON. A workflow **variable** or an environment variable both work; the code below reads `$vars.RALLLY_WEBHOOK_SECRET`.+ </Step>++ <Step title="Verify the signature in a Code node">+ Add a **Code** node after the Webhook node, mode **Run Once for All Items**, and paste:++ ```js+ const { createHmac, timingSafeEqual } = require("crypto");++ const item = $input.first();+ const header = item.json.headers["x-rallly-signature"] ?? "";+ const rawBody = await this.helpers.getBinaryDataBuffer(0, "data");++ const parts = Object.fromEntries(+ header.split(",").map((part) => part.split("=")),+ );+ const timestamp = Number(parts.t);+ if (Math.abs(Date.now() / 1000 - timestamp) > 300) {+ throw new Error("Signature timestamp is missing or older than five minutes");+ }+ if (!/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) {+ throw new Error("Signature is not a SHA-256 digest");+ }++ const expected = createHmac("sha256", $vars.RALLLY_WEBHOOK_SECRET)+ .update(`${parts.t}.`)+ .update(rawBody)+ .digest();+ if (!timingSafeEqual(expected, Buffer.from(parts.v1, "hex"))) {+ throw new Error("Signature does not match");+ }++ return [{ json: JSON.parse(rawBody.toString("utf8")) }];+ ```++ A request that fails any check stops the workflow with an error, and the node outputs the verified event body as the item. Everything after this node can trust `$json.type` and `$json.data`.++ On self-hosted n8n, `require("crypto")` needs the built-in module allowed: set `NODE_FUNCTION_ALLOW_BUILTIN=crypto` in n8n's environment. n8n Cloud allows it already.+ </Step>++ <Step title="Branch on the event type">+ Add a **Switch** node on `{{ $json.type }}` with one output per event you subscribed to, for example `poll.closed`, `poll.scheduled` and `poll.participant.created`. Add a fallback output and leave it unconnected: Rallly may add event types without a version change, and an unknown type should be ignored, not treated as an error.+ </Step>++ <Step title="Fetch the poll">+ The event carries the poll's id and nothing else about it, so add an **HTTP Request** node:++ - **Method** `GET`+ - **URL** `https://api.rallly.co/v1/polls/{{ $json.data.poll.id }}`+ - **Authentication** `Generic Credential Type` β `Bearer Auth`, with a credential holding your Rallly API key from **Settings β API keys**++ For a `poll.participant.*` event, fetch the participant the same way: `https://api.rallly.co/v1/polls/{{ $json.data.poll.id }}/participants/{{ $json.data.participant.id }}` returns their name, email and availability.++ From here the poll and the participant are ordinary items: post to Slack, write a row to a sheet, or update your own system.+ </Step>+</Steps>++## Testing it++Use the Webhook node's **Test URL** while building, then register the **Production URL** in Rallly. A quick end-to-end check is to close and reopen a poll in Rallly and watch `poll.closed` and `poll.reopened` arrive.++## When something fails++- **Signature does not match** on every request: Raw Body is off, or the secret in n8n is not the one Rallly showed when the endpoint was created. Delete and re-add the endpoint if the secret is lost.+- **Timestamp older than five minutes**: the n8n host's clock is wrong, or the request was a replay. Rallly's retries are signed fresh, so a stale timestamp is never a retry.+- **Endpoint disabled in Rallly**: twenty deliveries in a row exhausted their retries. Fix the workflow, then re-enable the endpoint from the settings page; events from while it was disabled are not replayed.diff --git a/apps/docs/api-reference/webhooks/security.mdx b/apps/docs/api-reference/webhooks/security.mdxnew file mode 100644index 000000000..8a069b6bc--- /dev/null+++ b/apps/docs/api-reference/webhooks/security.mdx@@ -0,0 +1,58 @@+---+title: "Security"+icon: "shield-check"+description: "Verify that a request came from Rallly before acting on it."+---++Anyone who knows your endpoint's URL can send it a request. The signing secret is what tells a genuine delivery from a forged one, so verify every request before you trust its body.++## The signing secret++Each endpoint has its own secret, shown once when the endpoint is created. Store it as you would any secret: in an environment variable or a secrets manager, never in client-side code or a repository. If it leaks, delete the endpoint and add it again; that mints a new secret.++Deliveries do not come from a fixed set of IP addresses, so allowlisting is not a substitute for verifying the signature.++## The signature header++Every request carries:++```http+X-Rallly-Signature: t=1736670600,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd+```++`t` is the time the request was signed, in seconds since the Unix epoch. `v1` is the hex HMAC-SHA256, keyed with the signing secret, of the string `<t>.<raw body>`: the timestamp, a full stop, and the request body exactly as received.++## Verifying it++1. Read the raw body as bytes. Do not parse and re-serialise it first; any change to whitespace or key order changes the digest.+2. Split the header on `,` and each part on `=` to get `t` and `v1`.+3. Check that `v1` is exactly 64 lowercase hex characters. Anything else is not a digest and is rejected before comparing, so a malformed header cannot make the comparison throw.+4. Compute HMAC-SHA256 of `<t>.<raw body>` with the secret and compare it to `v1` with a constant-time comparison.+5. Reject the request if `t` is more than a few minutes from now. This stops a captured request from being replayed later.++```ts+import { createHmac, timingSafeEqual } from "node:crypto";++function verify(header: string, rawBody: string, secret: string) {+ const parts = Object.fromEntries(+ header.split(",").map((part) => part.split("=") as [string, string]),+ );+ const timestamp = Number(parts.t);+ if (Math.abs(Date.now() / 1000 - timestamp) > 300) {+ return false; // missing, or older than five minutes+ }+ if (!/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) {+ return false; // not a SHA-256 hex digest, so never worth comparing+ }+ const expected = createHmac("sha256", secret)+ .update(`${parts.t}.${rawBody}`)+ .digest();+ return timingSafeEqual(expected, Buffer.from(parts.v1, "hex"));+}+```++## After verifying++- Deduplicate on the body's `id`. Delivery is at least once, and retries of one event share it.+- Treat the body as a notification, not as authority over your data. When an action depends on the poll's current state, fetch `GET /polls/{pollId}` with your API key rather than trusting a snapshot.+- Respond `2xx` as soon as the request is stored. Work that takes longer than 10 seconds should happen after the response, or the delivery is retried.diff --git a/apps/docs/docs.json b/apps/docs/docs.jsonindex ca0d50036..343928009 100644--- a/apps/docs/docs.json+++ b/apps/docs/docs.json@@ -99,6 +99,20 @@"GET /v1/polls/{pollId}/participants","GET /v1/polls/{pollId}/participants/{participantId}"]+ },+ {+ "group": "Webhooks",+ "pages": [+ "api-reference/webhooks",+ "api-reference/webhooks/events",+ "api-reference/webhooks/security",+ {+ "group": "Guides",+ "pages": ["api-reference/webhooks/guides/n8n"],+ "icon": "book-open"+ }+ ],+ "tag": "Beta"}]},diff --git a/apps/docs/style.css b/apps/docs/style.cssindex c00c89885..ce7576814 100644--- a/apps/docs/style.css+++ b/apps/docs/style.css@@ -66,3 +66,11 @@/* biome-ignore lint/complexity/noImportantStyles: same */color: var(--shiki-dark) !important;}++/* An identifier in a table cell (an event name, a header, an error code) is+ one token: wrapping it mid-word reads as two names. Let the column grow+ and the prose column take the wrapping instead. */+#content-area table td code,+#content-area table th code {+ white-space: nowrap;+}