Skip to content

Notification payload

Notification payloads contain the information sent to external systems when an event occurs.

The payload is intentionally small. Instead of including full row data, notifications provide identifiers that allow the receiving system to fetch additional information through the API if needed.

All notifications share the same basic payload structure.

Envelope fields

Every notification is delivered as a JSON object.

The payload contains two top‑level fields:

  • hook_id – identifier of the webhook configuration that produced the notification
  • rows – list of row identifiers affected by the event

These fields allow the receiving system to determine which webhook triggered the message and which rows were involved.

Common fields

Two fields are always present in the payload.

Field Description
hook_id Identifier of the webhook configuration
rows List of row IDs affected by the event

The rows field may contain one or many identifiers depending on how many rows were affected by the event.

Event-specific sections

Notifications currently use the same payload structure for all event types.

Both classification events and mutation events send the same payload format. The meaning of the row identifiers depends on the event that triggered the notification.

The receiving system can use the identifiers to request additional details from the API if necessary.

Compatibility and versioning

Payloads are designed to remain stable over time.

Important characteristics:

  • payloads are always delivered as JSON
  • the same payload is reused for retry attempts
  • notifications contain row identifiers only, not full data

This design keeps notifications lightweight and ensures external systems can reliably process events even when retries occur.

Related concepts