API Reference

Webhooks Reference

Blogree delivers content to your sites via HTTPS webhooks. This reference covers all webhook events, headers, payload schemas, retry behavior, and the delivery confirmation endpoint.

Delivery Headers

Every Blogree webhook request includes these HTTP headers:

Header	Example Value	Description
Content-Type	application/json	Payload encoding
X-Blogree-Signature	sha256=abc123...	HMAC-SHA256 of raw body
X-Blogree-Timestamp	1680432000	Unix timestamp of delivery
X-Blogree-Event	post.published	Event type
X-Blogree-Delivery	del_xyz789	Unique delivery ID
X-Blogree-Version	2026-04-01	API version

Webhook Events

post.published

Fired when a post is published immediately (Publish Now) or when a scheduled post's delivery time arrives.

{
  "event": "post.published",
  "post": {
    "id": "post_xyz789",
    "version": 3,
    "slug": "my-blog-post-title",
    "title": "My Blog Post Title",
    "excerpt": "Short summary of the post...",
    "body": {
      "html": "<h1>Title</h1><p>Content here...</p>",
      "markdown": "# Title\n\nContent here...",
      "json": { "type": "doc", "content": [...] }
    },
    "meta": {
      "title": "SEO Title | My Site",
      "description": "Meta description (max 160 chars)",
      "og_image": "https://cdn.example.com/og-image.jpg",
      "canonical_url": "https://primarysite.com/blog/my-post"
    },
    "tags": ["AI", "blogging", "automation"],
    "status": "published",
    "published_at": "2026-04-02T09:00:00Z"
  },
  "site": {
    "id": "site_abc123",
    "name": "My Tech Blog"
  },
  "delivered_at": "2026-04-02T09:00:03Z"
}

post.updated

Fired when a published post is edited and re-published. Your handler should update the existing post content by slug.

{
  "event": "post.updated",
  "post": {
    "id": "post_xyz789",
    "version": 4,  // incremented from 3
    "slug": "my-blog-post-title",
    "title": "Updated Title",
    // ... full post object with updated content
  },
  "previous_version": 3,
  "site": { "id": "site_abc123", "name": "My Tech Blog" }
}

post.deleted

Fired when a post is deleted from Blogree. Use this to remove the post from your site.

{
  "event": "post.deleted",
  "post": {
    "id": "post_xyz789",
    "slug": "my-blog-post-title"
  },
  "site": { "id": "site_abc123" },
  "deleted_at": "2026-04-05T14:30:00Z"
}

site.test

Fired when you click Test Delivery in the dashboard. Use to verify your endpoint is working.

{
  "event": "site.test",
  "test": true,
  "post": { ...sample post object with fake data },
  "site": { "id": "site_abc123", "name": "My Tech Blog" }
}

Retry Behavior

If your endpoint doesn't return 200 OK, Blogree retries delivery on this schedule:

Attempt 1

Immediate

On publish/schedule time

Attempt 2

+30 seconds

If attempt 1 fails

Attempt 3

+5 minutes

If attempt 2 fails

Attempt 4 (final)

+30 minutes

If attempt 3 fails

⚠️

After all 4 attempts fail, the delivery is marked 'failed'. You can trigger a manual retry from the Analytics dashboard or via the Analytics API.

Pull API — Delivery Confirmation

After successfully processing a webhook, your site can call the Pull API to explicitly confirm delivery. This gives Blogree accurate delivery metrics and allows you to report errors back.

POST /api/pull/confirm
X-API-Key: bk_live_xxxxxxxxxxxx
Content-Type: application/json

{
  "post_id": "post_xyz789",
  "site_id": "site_abc123",
  "status": "delivered",     // or "failed"
  "error_message": null,     // error description if status is "failed"
  "metadata": {
    "your_post_id": 12345    // optional: any data to store with delivery record
  }
}

Pull API — Fetch Posts

Your site can also pull posts on-demand rather than waiting for webhook delivery:

// Fetch all published posts
GET /api/pull/posts?limit=20&page=1
X-API-Key: bk_live_xxxxxxxxxxxx

// Fetch single post by slug
GET /api/pull/posts/my-blog-post-slug
X-API-Key: bk_live_xxxxxxxxxxxx

// Fetch posts by tag
GET /api/pull/posts?tag=AI+blogging&limit=10
X-API-Key: bk_live_xxxxxxxxxxxx