Webhook alerting

Gluesync can deliver real-time event notifications to any HTTP endpoint via webhooks. This page explains how to configure webhook endpoints, choose which events to receive, filter by severity, add custom headers, and manage delivery history.

How webhooks work

When a significant event occurs — a pipeline starts, an anomaly is detected, an agent goes unhealthy — Gluesync dispatches an HTTP POST request to every enabled and matching webhook endpoint.

The payload follows the CloudEvents specification. Each event carries:

  • A type field identifying the event (e.g., gluesync.alert.data-flow-stall-detected)

  • A severity field: CRITICAL, WARNING, or INFO

  • Pipeline and entity identifiers

  • A human-readable message and structured data payload

Configuring webhooks

Webhook endpoints are configured under Settings → Notifications → Webhooks in the Control Plane.

Managing webhook configurations

You can create any number of webhook configurations. Each one appears as a card in the list showing its name, URL, enabled status, the number of subscribed events, the number of selected severities, and whether signing or custom headers are configured.

Use the Add webhook button to create a new configuration, or click the edit icon on an existing card to modify it.

Webhook editor fields

Field Required Description

Name

Yes

A human-readable label shown in the list and in delivery logs.

Endpoint URL

Yes

The HTTPS endpoint that receives POST requests. Gluesync sends a JSON body — no query strings, no GET requests.

Signing secret

No

When set, Gluesync signs each request body with HMAC-SHA256 and sends the result as X-Gluesync-Signature: sha256=<hex>. Your endpoint must compute the same hash to verify authenticity. Leave empty for unauthenticated delivery.

Description

No

Free-text note for documentation purposes.

Enabled

Yes

When disabled, no deliveries are attempted for this webhook.

Enabled events

No

Subset of event types this webhook receives. Leave empty to receive all events.

Severity filter

No

Only deliver events at or above the selected severities. Leave empty to receive all severities.

Custom headers

No

Static key-value headers added to every delivery (for example, Authorization: Bearer <token>).

Object filters

No

Restrict deliveries to specific pipelines, groups, or entities. Leave empty to receive events from all objects.

Enabled events

The Enabled events multi-select exposes all available event types directly from the server, so you always see the canonical list without consulting documentation:

Event type Severity Description

ENTITY_SNAPSHOT_STARTED

INFO

A snapshot phase has begun for an entity

ENTITY_SNAPSHOT_COMPLETED

INFO

A snapshot phase completed successfully

ENTITY_SNAPSHOT_FAILED

CRITICAL

A snapshot phase failed

ENTITY_CDC_STARTED

INFO

Change data capture started for an entity

ENTITY_CDC_STOPPED

WARNING

Change data capture stopped

ENTITY_CDC_RELOADED

INFO

CDC reloaded (for example, after a connector restart)

ENTITY_UPSERTED

INFO

An entity configuration was created or updated

ENTITY_DELETED

WARNING

An entity was removed from a pipeline

GROUP_SNAPSHOT_STARTED

INFO

Group snapshot started

GROUP_SNAPSHOT_COMPLETED

INFO

Group snapshot completed

GROUP_CDC_STARTED

INFO

Group CDC started

GROUP_CDC_STOPPED

WARNING

Group CDC stopped

REPLICATION_LATENCY_THRESHOLD_EXCEEDED

WARNING / CRITICAL

End-to-end latency exceeded the configured static threshold

ROW_COUNT_DRIFT_DETECTED

WARNING / CRITICAL

Source and target row counts have diverged beyond the configured percentage

DATA_FLOW_STALL_DETECTED

WARNING / CRITICAL

A pipeline entity has stopped receiving data for longer than the stall duration

THROUGHPUT_ANOMALY_DETECTED

WARNING / CRITICAL

Throughput deviated from the EWMA baseline beyond the control limit

LATENCY_ANOMALY_DETECTED

WARNING / CRITICAL

Latency spike or sustained elevation detected by the pattern detector

ENTITY_HEARTBEAT_MISSED

CRITICAL

The entity sync-poll loop has not reported any heartbeat for longer than the configured silence window. Indicates agent-down or loop-crash scenarios.

AGENT_UNHEALTHY

CRITICAL

An agent has gone unhealthy

AGENT_RECOVERED

INFO

A previously unhealthy agent recovered

PIPELINE_ERROR

CRITICAL

A pipeline-level error occurred

PIPELINE_ERROR_RESOLVED

INFO

A previously errored pipeline recovered

TEST

INFO

Sent when you click Send test on a webhook configuration

Severity filter

Severity Meaning

INFO

Informational events (lifecycle changes, recoveries). Low noise.

WARNING

Degraded but not failed conditions. Recommend action.

CRITICAL

Failures or severe anomalies requiring immediate attention.

Setting the severity filter to WARNING means Gluesync delivers only events with severity WARNING or CRITICAL for that webhook. INFO events are silently dropped.

A common pattern is to configure two webhooks pointing to the same URL: one for WARNING+CRITICAL driving a Slack channel, and a separate one for CRITICAL only driving an on-call PagerDuty integration.

Custom headers

Add static headers to every webhook delivery. This is useful when the receiver requires an API key, bearer token, or content-type override.

  1. In the webhook editor, click Add header.

  2. Enter the header name (for example, Authorization).

  3. Enter the header value (for example, Bearer mytoken).

  4. Add as many headers as needed.

Headers with empty names are ignored. Duplicates are overwritten by the last occurrence.

Object filters

Restrict webhook deliveries to specific pipelines, groups, or entities. This is useful when different teams own different data flows and each team only wants events for their own scope.

Field Description

Pipeline

Select one or more pipelines. Only events originating from the chosen pipelines are delivered.

Group

Select one or more groups. The list is automatically narrowed when pipelines are selected.

Entity

Select one or more entities. The list is automatically narrowed when pipelines are selected.

Leave all three filters empty to receive events from every pipeline, group, and entity.

Signing and verifying payloads

Every delivery includes two tracing headers plus the optional signature:

X-Gluesync-Event:   <the CloudEvent type (e.g. gluesync.alert.data-flow-stall-detected)>
X-Gluesync-Delivery: <unique delivery UUID>
X-Gluesync-Signature: sha256=<HMAC-SHA256 of request body with your secret>  (only when a signing secret is set)

To verify in your receiver:

import hmac, hashlib

def verify(body: bytes, secret: str, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Testing a webhook

Before saving a webhook, click Send test to dispatch a TEST event to the endpoint. The UI shows a success notification if the delivery receives an HTTP 2xx response. If the delivery fails, check the error message and verify the endpoint URL, network connectivity, and any required headers.

Smart alerts

Smart alerts control when the anomaly detectors fire events. Configure global defaults under Settings → Smart alerts. A pipeline’s Smart alerts settings can override threshold, sensitivity, cooldown, enabled anomaly types, and monitored entities for that pipeline.

Threshold settings include static latency limits, row count drift, data flow stall detection, throughput anomaly detection, latency pattern detection, seasonal detection, and alert cooldown. A threshold hit also marks the affected pipeline or entity as WARNING, a non-blocking state distinct from ERROR.

For a detailed guide on every detector, its parameters, and default values, see Smart alerts. Threshold values are also exposed as Prometheus metrics for Grafana overlays — see the same page for PromQL examples.

Delivery logs and dead letters

Webhook deliveries are recorded in two queues visible under Settings → Notifications → Webhooks:

Queue Description

Delivery logs

Every attempted delivery, successful or not. Shows HTTP status, duration, and error messages.

Dead letters

Failed deliveries that exhausted all retry attempts.

Delivery logs

The delivery logs table is paginated (20 entries per page) and shows:

  • Status — OK or Fail tag

  • Event — the event type in human-readable form

  • Webhook — the configuration name that was targeted

  • HTTP — the HTTP response status code returned by the receiver

  • Duration — round-trip time in milliseconds

  • Time — localised timestamp of the attempt

Use the Refresh button to reload the latest entries and Purge logs to clear the entire queue.

Dead letters

Dead letters are deliveries that failed permanently after exhausting the retry policy. The dead letters table shows the same columns as delivery logs (without the status tag) and adds a Retry action for each row.

  • Click Retry on a single dead letter to re-attempt delivery immediately.

  • Click Purge dead letters to remove all failed deliveries from the queue.

Retention

Control how long delivery logs and dead letters are kept. The retention settings apply globally to all webhooks:

Setting Description

Max delivery logs

Maximum number of delivery log entries stored.

Max dead letters

Maximum number of dead letter entries stored.

Max retention days

Maximum age in days for delivery logs. Older entries are automatically removed.

Max dead letter days

Maximum age in days for dead letters. Older entries are automatically removed.

Retention values are saved together with the webhook configurations. Adjust them to balance observability with storage usage.