Webhooks

Webhooks are user-defined HTTP callbacks.

Miniflux can publish new feed entries to a custom API endpoint. You can easily set up your own personal webhook receiver and extend Miniflux by writing your own scripts.

This feature has been available since Miniflux 2.0.48.

Configuring a Webhook in Miniflux

  1. Go to Settings > Integrations > Webhook
  2. Enter the URL of your webhook endpoint

The auto-generated secret is used to validate the payload.

Webhook Event Types

Miniflux supports different types of event:

Webhook HTTP Request

Validating Signatures from Miniflux

Miniflux will sign all inbound requests to your application with an X-Miniflux-Signature HTTP header. The signature uses the HMAC-SHA256 hashing algorithm with the request body and the auto-generated secret key that is visible in Settings > Integrations > Webhook.

Example in PHP:

// The secret value is visible in Settings > Integrations > Webhook
$secret = 'c4fdaf87900b72777cbe8e97d17b97a87d28ae078a462ef4ac5f2541fcf00ce6';

// Payload is the request body
$payload = file_get_contents('php://input');

$hmac = hash_hmac('sha256', $payload, $secret);

if (! hash_equals($hmac, $_SERVER['HTTP_X_MINIFLUX_SIGNATURE'])) {
    die('Incorrect signature!');
}

HTTP Authentication

Miniflux supports HTTP Basic Authentication. This allows you to password protect the webhook URLs on your web server so that only you and Miniflux can access them.

You may provide a username and password via the following URL format: https://username:password@webhook.example.org/

New Entries Event Request

POST /your-webhook-endpoint HTTP/1.1

Content-Type: application/json
User-Agent: Miniflux/2.0.48
X-Miniflux-Signature: 7ff170cfd8c173fd5084e0f51ee6ac3eae8acff443f11f9168961cebf836e38f
X-Miniflux-Event-Type: new_entries

{
  "event_type": "new_entries",
  "feed": {
    "id": 8,
    "user_id": 1,
    "feed_url": "https://example.org/feed.xml",
    "site_url": "https://example.org",
    "title": "Example website",
    "checked_at": "2023-09-10T12:48:43.428196-07:00"
  },
  "entries": [
    {
      "id": 231,
      "user_id": 1,
      "feed_id": 3,
      "status": "unread",
      "hash": "1163a93ef12741b558a3b86d7e975c4c1de0152f3439915ed185eb460e5718d7",
      "title": "Example",
      "url": "https://example.org/article",
      "comments_url": "",
      "published_at": "2023-08-17T19:29:22Z",
      "created_at": "2023-09-10T12:48:43.428196-07:00",
      "changed_at": "2023-09-10T12:48:43.428196-07:00",
      "content": "<p>Some HTML content</p>",
      "share_code": "",
      "starred": false,
      "reading_time": 1,
      "enclosures": [{
          "id": 158,
          "user_id": 1,
          "entry_id": 231,
          "url": "https://example.org/podcast.mp3",
          "mime_type": "audio/mpeg",
          "size": 63451045,
          "media_progression": 0
      }],
      "tags": ["Some category", "Another label"]
    }
  ]
}

Save Entry Event Request

POST /your-webhook-endpoint HTTP/1.1

Content-Type: application/json
User-Agent: Miniflux/2.0.48
X-Miniflux-Signature: 7ff170cfd8c173fd5084e0f51ee6ac3eae8acff443f11f9168961cebf836e38f
X-Miniflux-Event-Type: save_entry

{
  "event_type": "save_entry",
  "entry": {
    "id": 592,
    "user_id": 1,
    "feed_id": 9,
    "status": "read",
    "hash": "ed97d338e7ea23fd82d14f0623c1953a22ddda32ce406f0cdfbd14632db8ff8b",
    "title": "Some example",
    "url": "https://example.org/article",
    "comments_url": "",
    "published_at": "2023-09-10T19:13:40Z",
    "created_at": "2023-09-10T20:06:23.000332Z",
    "changed_at": "2023-09-11T00:39:49.615812Z",
    "content": "Some HTML content",
    "author": "",
    "share_code": "",
    "starred": false,
    "reading_time": 1,
    "enclosures": [
      {
        "id": 1492,
        "user_id": 1,
        "entry_id": 592,
        "url": "https://example.org/file.zip",
        "mime_type": "application/octet-stream",
        "size": 0,
        "media_progression": 0
      }
    ],
    "tags": [],
    "feed": {
      "id": 9,
      "user_id": 1,
      "feed_url": "https://example.org/feed.xml",
      "site_url": "https://example.org/,
      "title": "Example website",
      "checked_at": "2023-09-10T20:07:22.956279Z"
    }
  }
}

Notes