Guides

Analytics Guide

Blogree's analytics dashboard gives you complete visibility into every post delivery — success rates, failure reasons, retry history, and performance trends across all connected sites. This guide covers reading the dashboard, debugging failures, and using the Analytics API.

1. Dashboard Overview

Navigate to Analytics in the left sidebar. The overview page shows four key metrics at the top:

Total Deliveries

Total webhook delivery attempts across all sites and time ranges selected

Success Rate

Percentage of deliveries that received a 200 OK response on the first attempt

Failed Deliveries

Deliveries where all retry attempts (×3) failed to get a 200 OK response

Avg. Delivery Time

Mean time from publish/schedule trigger to confirmed delivery across all sites

Delivery Timeline Chart

The main chart shows delivery volume over time (daily/weekly/monthly). Hover over any bar to see the exact success and failure counts for that period. Use the date range picker to zoom in on specific periods.

Per-Site Breakdown

Below the main chart, a table lists each connected site with its individual delivery metrics. Sort by success rate to quickly identify sites with delivery problems.

2. Delivery Status Reference

Status	Description	Action Required
delivered	Webhook received and confirmed with 200 OK on first attempt	None
delivered_retry	Succeeded on 2nd or 3rd retry attempt (30s or 5min delay)	Check site uptime — intermittent issues detected
pending	Delivery in progress or scheduled for future delivery	None — delivery will proceed automatically
retrying	First attempt failed; retry in progress	Check site webhook URL is accessible
failed	All 3 retry attempts failed; no 200 OK received	Debug required — see Section 4 below

3. Post-Level Delivery Detail

Click any post in the Posts → Published list to open the delivery detail panel. This shows:

Each connected site's delivery status and timestamp
HTTP response code received from your site's webhook endpoint
Request body sent (HMAC signature, post payload)
Retry history with timestamps and response codes
Option to manually trigger a re-delivery

Manual Re-delivery

If a delivery failed and you've fixed the issue on your site, click Retry Delivery on the delivery detail page. This triggers a fresh delivery attempt — not counted toward the original retry limit.

4. Debugging Failed Deliveries

Common failure causes and fixes

404 on webhook URL

Go to Sites → your site → Edit. Verify the webhook URL matches your actual route (e.g. /api/blogree/route.ts for Next.js App Router).

401 Unauthorized

Your HMAC signature verification is failing. Check BLOGREE_WEBHOOK_SECRET in your .env matches the secret shown in Sites → Settings → Webhook Secret.

500 Server Error

Your webhook handler is throwing. Check your server logs. Common issue: revalidatePath() not available in wrong context — wrap in try/catch.

Timeout (>30s)

Your webhook handler is taking too long. Move heavy operations to a background job. The webhook should return 200 immediately after receiving the payload.

SSL/TLS Error

Your site's SSL certificate is expired or self-signed. Blogree requires valid HTTPS for all webhook endpoints.

✅

Use the built-in webhook tester in Sites → your site → Test Delivery to send a sample payload to your endpoint and see the raw HTTP response before publishing real posts.

5. Analytics API

Fetch analytics data programmatically to build custom dashboards or integrate with your existing reporting tools.

GET /api/analytics/overview

GET /api/analytics/overview?from=2026-03-01&to=2026-04-01&site_id=site_abc123
Authorization: Bearer <your_jwt_token>

// Response
{
  "period": { "from": "2026-03-01", "to": "2026-04-01" },
  "totals": {
    "deliveries": 847,
    "successful": 831,
    "failed": 16,
    "retried": 44,
    "success_rate": 98.1,
    "avg_delivery_ms": 1240
  },
  "sites": [
    {
      "id": "site_abc123",
      "name": "My Tech Blog",
      "deliveries": 412,
      "success_rate": 99.3
    }
  ]
}

GET /api/analytics/deliveries

GET /api/analytics/deliveries?granularity=day&from=2026-03-01&to=2026-04-01
Authorization: Bearer <your_jwt_token>

// Response
{
  "granularity": "day",
  "data": [
    { "date": "2026-03-01", "delivered": 28, "failed": 1, "retried": 3 },
    { "date": "2026-03-02", "delivered": 32, "failed": 0, "retried": 0 },
    ...
  ]
}

GET /api/analytics/posts/:id/deliveries

GET /api/analytics/posts/post_xyz789/deliveries
Authorization: Bearer <your_jwt_token>

// Response
{
  "post_id": "post_xyz789",
  "deliveries": [
    {
      "site_id": "site_abc123",
      "site_name": "My Tech Blog",
      "status": "delivered",
      "attempts": 1,
      "delivered_at": "2026-04-02T09:01:14Z",
      "response_code": 200,
      "response_time_ms": 834
    },
    {
      "site_id": "site_def456",
      "site_name": "Client Site",
      "status": "delivered_retry",
      "attempts": 2,
      "delivered_at": "2026-04-02T09:02:45Z",
      "response_code": 200,
      "history": [
        { "attempt": 1, "timestamp": "2026-04-02T09:01:12Z", "response_code": 503, "error": "Service Unavailable" },
        { "attempt": 2, "timestamp": "2026-04-02T09:01:42Z", "response_code": 200 }
      ]
    }
  ]
}

6. Email Notifications

Configure delivery failure notifications in Settings → Notifications. Options include:

Immediate email on every failed delivery
Daily digest of all failures
Weekly delivery performance summary
Slack webhook integration for real-time alerts (Pro+)