Skip to main content

alert.*

Alert webhook payloads contain a snapshot of the current alert and its cumulative timeline in data.events. Rootly emits alert.updated when the alert itself changes or a timeline event is added. Use the top-level event.id to deduplicate webhook delivery retries. Because the timeline is cumulative, reconcile the complete data.events snapshot by each entry’s id: insert unseen events and refresh stored copies of known events when their fields change. Events are ordered by created_at, oldest first. Adding a timeline event emits alert.updated; editing or deleting an existing timeline event does not. When a timeline event triggers alert.updated, Rootly creates one idempotent outbound event for that timeline entry. Its cumulative data.events snapshot ends at the triggering entry, so the final array item is the event associated with that delivery. This cutoff applies to data.events; top-level alert fields and timestamps reflect the settled alert and can include state persisted after the triggering timeline entry. Adjacent timeline events are sent in separate deliveries instead of being collapsed into one snapshot. A retry of the same timeline event retains the same top-level event.id. An alert field can still change without creating a timeline event. In that case, alert.updated can contain no new data.events entry. Do not treat the cumulative array as append-only: a known event ID can reappear in a later snapshot with corrected metadata. Two deliveries with different top-level event.id values are distinct alert snapshots, even when their timelines are identical. ISO 8601 timestamps can represent the same instant with different UTC offsets, so do not use their displayed offset to identify duplicate deliveries.

Alert context

Alert payloads include Rootly-owned context without requiring another API request:
  • data.created_by: The complete user who created the alert from a Rootly interface. The field is omitted when the creation event has no user, such as an alert ingested from a monitoring source.
  • data.alert_urgency: The current urgency, including id, name, description, urgency, and position.
  • data.data.rootly.notification_target: The normalized type and id of the most recently accepted paging target. The second data is the alert object’s own data hash. Rootly adds this nested value without replacing source-specific or customer-provided keys in that hash. For a multi-target page, this singular value is the last successfully processed target, not the authoritative target set; reconcile the separate alert.updated deliveries for the request’s action: paged timeline events and their notification_target objects to collect every successful destination.

Alert Ownership Changes

Manual ownership transfers preserve the existing kind: action and action: paged contract. They add page_reason: manual_reassignment so consumers can distinguish an explicit destination change from other pages. For multi-target pages, adding or removing a destination counts as an ownership change, and each successful page event from that request includes the reason. The same page_reason discriminator is available on alert events returned by the public API and mobile API.
Progression between levels of the current escalation policy does not include page_reason: manual_reassignment.
For a manual page, Rootly suppresses delivery while the page operation is in progress. After it settles, Rootly emits one event-specific alert.updated for each successful page event. When the page creates a new alert, Rootly emits the normal alert.created event and these alert.updated deliveries; subscribe to alert.updated for the resulting page events and ownership metadata. For a multi-target page, Rootly determines page_reason from the destinations that were successfully paged. Each cumulative snapshot ends at its successful page event and can include corrected metadata on earlier events when a later success changes the batch reason. Use the top-level event.id to deduplicate retries and each timeline event’s id to reconcile the cumulative data.events list. Ownership-change timeline events include:
  • user: The complete user associated with the event. For an action event this is the actor; for a notification event this is the recipient. user_id remains available for compatibility.
  • paged_user: For a user-group page that fans out to an individual on-call user, the complete recipient user. This keeps the selected group in notification_target while identifying who was actually paged. The field is omitted for other target types.
  • notification_target: On the manual-page event, the notification target originally selected by the actor. Supported manual-reassignment types are escalation_policy, group, service, functionality, and user.
group is the serialized target type for a Team selected in the Rootly interface. Every notification_target includes stable type and id fields. When the selected resource still exists, Rootly also includes its standard outgoing webhook fields: Downstream notification events can also identify the channel or space that received a notification. These are not manual-reassignment targets: If the referenced resource was deleted or is otherwise unavailable when the webhook is generated, notification_target remains present with only its stored type and id. Consumers should therefore treat all additional fields as optional.

Snooze and urgency context

Timeline events expose the values associated with snooze and urgency changes:
  • An event with kind: action and action: snoozed includes snooze_duration_in_minutes.
  • An event with kind: alert_urgency and action: updated includes the new alert_urgency object and the previous_alert_urgency object when each referenced urgency is available.
JSON
When an alert is transferred to an escalation policy with no pageable targets, the manual-page event still identifies the selected policy and the resulting alert.updated payload reports data.status as open. If the alert was previously non-open, the timeline also includes a kind: status_update event with action: open; an alert that was already open does not record another status transition.

alert.updated Manual Reassignment Example

The following representative payload is the event-specific delivery for the manual paged event, so that event is the final item in data.events. The alert snapshot already reports data.status as open. If the transfer also creates a later status_update / open event, Rootly sends it in a separate alert.updated delivery whose timeline ends at that status event. Optional fields may vary by alert and serializer version:
JSON

genius_workflow_run.*

JSON

incident.*

JSON
When custom fields on action items are enabled for your team, each action item in the action_items array carries a custom_field_selections array for the fields placed on its form. Each entry looks like:
JSON
Free-text, number, and date fields populate value; reference-type fields (user, team, service, catalog entity, environment, cause, incident type) populate the matching selected_* array instead.

incident_post_mortem.*

JSON

pulse.*

JSON