Connection health notifications

Receive signed connection-health webhooks, verify their signatures, and handle recovery and retries.

Connection-health notifications report when a connection becomes ready, requires reconnection, or is revoked. An organization-bound destination is configured by the Arc0 operator and enabled by a project administrator. General provider triggers and arbitrary event subscriptions are planned separately.

For self-service project lifecycle notifications, including execution failures and approvals, see Project webhooks. Those settings are separate from the operator-configured connection-health destinations described here.

Events

The event type is connection.health. Its status is active, reauth_required, or revoked. Repeated writes of the same connection status do not produce another event. A transition back to active produces a recovery notification.

An alert follows the runtime's decision that the connection requires reconnection; it does not fire for each failed tool call. Refresh rate limits are retried without a status-change alert. Other refresh failures can require reconnection. This is a state-change threshold, not a configurable number of failed requests.

{
  "type": "connection.health",
  "id": "event-id",
  "connectionId": "connection-id",
  "appId": "github",
  "status": "reauth_required",
  "occurredAt": "2026-10-07T12:00:00Z"
}

No token, provider error body or tool result appears in the notification.

Verify the signature

Deliveries include three headers:

arc0-event-id: event-id
arc0-timestamp: 1791374400
arc0-signature: <64-character hexadecimal signature>

The signature is HMAC-SHA256 of eventId.timestamp.rawBody with the assigned signing secret. Verify the original bytes, timestamp freshness and event ID before parsing or acting on the body.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(
  rawBody: string,
  eventId: string,
  timestamp: string,
  signature: string,
  secret: string,
): boolean {
  if (!/^\d+$/.test(timestamp) || !/^[a-f0-9]{64}$/.test(signature)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${eventId}.${timestamp}.${rawBody}`)
    .digest();
  return timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}

Retries and recovery

Return a 2xx after durably accepting the event. Delivery is at least once: deduplicate by the stable event ID, which remains unchanged across retries. Every attempt has a fresh timestamp and signature. Do not assume events arrive in order; use occurredAt to avoid applying an older state after a newer one.

The worker retries failures with exponential backoff for up to eight attempts. Expired worker leases recover after a crash. Diagnostics show pending deliveries, failed deliveries and the last successful delivery. A failed delivery does not automatically disable the destination.

Email notifications

The same state transitions can be delivered by email when the operator has configured a verified sender and explicitly authorized recipient addresses. Recipients are fixed in that configuration; agents cannot choose an email address. Email uses the same durable queue and event deduplication.

On this page