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.