> ## Documentation Index > Fetch the complete documentation index at: https://support.rallly.co/llms.txt > Use this file to discover all available pages before exploring further. # Events > 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 theme={null} { "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=,v1=`. See [Security](/api-reference/webhooks/security) | | `User-Agent` | `Rallly-Webhooks/1.0` | ## Events Event names are `.`, or `..` 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 theme={null} { "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 A poll was created, from the app or the API. ```json theme={null} { "version": "2026-09-20", "id": "cm5h8x2k40000q9l4f7e2d3an", "type": "poll.created", "createdAt": "2025-01-12T08:30:00.000Z", "data": { "poll": { "id": "Xk3pQ9vLm2Ab" } } } ``` The poll's details, options or settings changed. The event says that something changed, not what; fetch the poll for its current state. ```json theme={null} { "version": "2026-09-20", "id": "cm5h8x2k40000q9l4f7e2d3an", "type": "poll.updated", "createdAt": "2025-01-12T08:30:00.000Z", "data": { "poll": { "id": "Xk3pQ9vLm2Ab" } } } ``` The poll stopped accepting responses. `reason` is `manual` when the organizer closed it and `auto` when it closed because every option had passed. ```json theme={null} { "version": "2026-09-20", "id": "cm5h8x2k40000q9l4f7e2d3an", "type": "poll.closed", "createdAt": "2025-01-12T08:30:00.000Z", "data": { "poll": { "id": "Xk3pQ9vLm2Ab" }, "reason": "manual" } } ``` A closed poll accepts responses again. ```json theme={null} { "version": "2026-09-20", "id": "cm5h8x2k40000q9l4f7e2d3an", "type": "poll.reopened", "createdAt": "2025-01-12T08:30:00.000Z", "data": { "poll": { "id": "Xk3pQ9vLm2Ab" } } } ``` 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 theme={null} { "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 } } } ``` The poll was deleted. `GET /polls/{pollId}` returns `404` from now on, so anything you need about it must already be stored. ```json theme={null} { "version": "2026-09-20", "id": "cm5h8x2k40000q9l4f7e2d3an", "type": "poll.deleted", "createdAt": "2025-01-12T08:30:00.000Z", "data": { "poll": { "id": "Xk3pQ9vLm2Ab" } } } ``` Someone responded to the poll. ```json theme={null} { "version": "2026-09-20", "id": "cm5h8x2k40000q9l4f7e2d3an", "type": "poll.participant.created", "createdAt": "2025-01-12T08:30:00.000Z", "data": { "poll": { "id": "Xk3pQ9vLm2Ab" }, "participant": { "id": "cm5j2r8wb0003q9l4a1x6p0zt" } } } ``` A participant changed their response or their name. ```json theme={null} { "version": "2026-09-20", "id": "cm5h8x2k40000q9l4f7e2d3an", "type": "poll.participant.updated", "createdAt": "2025-01-12T08:30:00.000Z", "data": { "poll": { "id": "Xk3pQ9vLm2Ab" }, "participant": { "id": "cm5j2r8wb0003q9l4a1x6p0zt" } } } ``` A response was removed, by the participant or the organizer. Fetching the participant returns `404`. ```json theme={null} { "version": "2026-09-20", "id": "cm5h8x2k40000q9l4f7e2d3an", "type": "poll.participant.deleted", "createdAt": "2025-01-12T08:30:00.000Z", "data": { "poll": { "id": "Xk3pQ9vLm2Ab" }, "participant": { "id": "cm5j2r8wb0003q9l4a1x6p0zt" } } } ``` ## Test events **Send test event** in the endpoint's menu on the settings page sends a `ping` to that endpoint straight away. It goes out whatever events the endpoint subscribes to, and it is signed and sent like any other event, so it checks your URL, your signature verification and your response in one go. ```json theme={null} { "version": "2026-09-20", "id": "ping_V1StGXR8Z5jdHi6BmyT", "type": "ping", "createdAt": "2025-01-12T08:30:00.000Z", "data": {} } ``` A `ping` carries no data and is never retried. Respond with a `2xx` and otherwise ignore it. A failed test does not count toward disabling the endpoint. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.