API Documentation

Overview

The Recover API gives you programmatic access to recovery events, webhook registration, and dashboard metrics. Use it to query recovery data, build custom alerts, or integrate recovery insights into your own dashboards.

The base URL for all API requests is:

All requests and responses use JSON. Authentication is required for all endpoints except the webhook receiver.

Authentication

Authenticated endpoints require a Bearer JWT token in the Authorization header. Retrieve your API key from Settings → Account.

Authorization: Bearer your-jwt-token-here

Internal endpoints (dashboard metrics, admin analytics) use the X-Internal-Key header instead of Bearer tokens. This key is available in your Settings page.

Webhooks

Recover receives Stripe webhook events on your behalf. The endpoint below is registered with Stripe when you connect your account. You do not need to configure this manually.

Stripe events handled:

• invoice.payment_failed — triggers the dunning sequence for the affected customer
• invoice.paid — marks a recovery as successful, stops the dunning sequence
• payment_intent.payment_failed — handles one-time payment failures
• customer.subscription.deleted — marks the recovery as lost

All webhook payloads are verified using Stripe's signature verification before processing.

{
  "id": "evt_1PxKJ2HjQ9kdnRw7abcdef",
  "type": "invoice.payment_failed",
  "data": {
    "object": {
      "id": "in_1PxKJ2HjQ9kdnRw7xyz",
      "customer_email": "user@example.com",
      "amount_due": 4900,
      "last_finalization_error": {
        "decline_code": "insufficient_funds"
      }
    }
  }
}

Recovery Events API

Query recovery events for your account. Requires X-Internal-Key authentication.

Returns aggregated recovery metrics and recent events.

curl -H "X-Internal-Key: your-key" \
  https://fourthngoal.ai/fourthngoal/recover/dashboard

{
  "recovered_mtd": 3840,
  "recovery_rate": 0.68,
  "failed_payments_mtd": 24,
  "roi_multiple": 132,
  "events": [
    {
      "customer_email_masked": "ma***@gmail.com",
      "decline_type": "soft",
      "amount": 4900,
      "date": "2025-04-20",
      "status": "recovered"
    }
  ]
}

Payment Update Page

Each failed payment generates a per-customer, tokenized payment update URL. Customers land on this page to update their card via Stripe's secure Billing Portal session.

The token is a short-lived JWT tied to the specific customer and invoice. Tokens expire after 7 days. The page renders with your product branding (product name configured in Settings).

Creates a Stripe Billing Portal session and redirects the customer. Requires the token in the request body.

Rate Limits

API requests are rate-limited to protect service stability.

• Authenticated endpoints: 100 requests per minute per API key
• Webhook endpoint: No rate limit — all Stripe events are processed
• Public endpoints: 60 requests per minute per IP

Rate-limited requests receive a 429 Too Many Requests response with a Retry-After header indicating when to retry.