alert.*
Alert webhook payloads contain a snapshot of the current alert and its cumulative timeline indata.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, includingid,name,description,urgency, andposition.data.data.rootly.notification_target: The normalizedtypeandidof the most recently accepted paging target. The seconddatais 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 separatealert.updateddeliveries for the request’saction: pagedtimeline events and theirnotification_targetobjects to collect every successful destination.
Alert Ownership Changes
Manual ownership transfers preserve the existingkind: 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.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_idremains 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 innotification_targetwhile 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 areescalation_policy,group,service,functionality, anduser.
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: actionandaction: snoozedincludessnooze_duration_in_minutes. - An event with
kind: alert_urgencyandaction: updatedincludes the newalert_urgencyobject and theprevious_alert_urgencyobject when each referenced urgency is available.
JSON
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.*
- genius_workflow_run.queued
- genius_workflow_run.started
- genius_workflow_run.completed
- genius_workflow_run.failed
- genius_workflow_run.canceled
JSON
incident.*
JSON
When custom fields on action items are enabled for your team, each action item in the Free-text, number, and date fields populate
action_items array carries a custom_field_selections array for the fields placed on its form. Each entry looks like:JSON
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