Retrybase documentation

01

How Retrybase works

Your backend reports normalized failures and heartbeats. Retrybase classifies each event, opens or updates the connection incident, waits through a short correlation window, and suppresses customer notifications when the evidence points to a provider-wide incident.

1. Observe. Accept a failure or notice a missing heartbeat.
2. Classify. Translate provider-specific symptoms into a stable failure class.
3. Correlate. Separate one broken connection from a provider incident.
4. Recover. Deliver one branded, time-limited reconnection path.
5. Verify. Accept the host application’s attempt-bound health probe.
6. Measure. Record delivery, recovery time, recurrence, and revenue context.

02

Send your first failure event

Register a connection with its provider and your HTTPS reconnect URL, then report failures with a project-scoped ingestion key. Event IDs must remain stable across retries.

POST /v1/events/failures
{
  "schema_version": "2026-09-19",
  "event_id": "failure_01J...",
  "connection_external_id": "customer_42_salesforce",
  "occurred_at": "2026-09-21T18:45:57.000Z",
  "provider": "salesforce",
  "code": "INVALID_SESSION_ID",
  "http_status": 401,
  "metadata": { "plan": "growth", "mrr": 2400 }
}

A successful request returns 202 Accepted and a durable receipt. Duplicate event IDs return the same logical receipt and do not create a second workflow.

Heartbeats

Send periodic heartbeats for connections that can fail silently. A heartbeat reports that your instrumentation is alive; it does not automatically prove a previous recovery succeeded unless it carries qualified provider-check evidence.

03

The security boundary

Retrybase is a control plane, not a token vault or integration proxy. Your application owns provider authorization, credentials, API calls, and customer records.

Secret-looking fields are redacted before storage. Recovery links and return state are separately signed, short-lived, rate-limited, and bound to a specific attempt.

04

Recovery lifecycle

Healthy

No unresolved connection incident.

Triaging

Failure accepted while correlation is still open.

Action required

A customer-fixable problem has survived correlation.

Recovery started

The end user intentionally launched the reconnect flow.

Verification pending

The browser returned; the host probe remains authoritative.

Healthy again

An authenticated, attempt-bound verification succeeded.

Verification may arrive before the browser return. Retrybase accepts that ordering because the provider health result is authoritative and the browser return is funnel instrumentation.

05

Salesforce reference flow

The reference host uses Authorization Code with PKCE S256. Salesforce tokens are encrypted at rest inside the host’s isolated SQLite volume and never cross into Retrybase. After authorization, the host discovers the newest API version, calls only its record-free /limits endpoint, and posts the result for the exact recovery attempt.

The live acceptance path has completed with a delivered email, browser launch, Salesforce approval, successful health probe, verified outcome, and a healthy Retrybase connection.

06

Operating Retrybase

• Use separate ingestion, verification, and management keys.
• Keep a stable event ID and verification ID across retries.
• Configure a verification window that matches your probe cadence.
• Alert on old outbox work, late scheduled work, dead letters, and missing delivery callbacks.
• Review heartbeat coverage before treating a green dashboard as complete evidence.
• Run recurring backup restore drills, not only backup checks.