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 events:

• new_entries: Event sent during a feed refresh when new entries are discovered.
• save_entry: Event sent when the end-user saves an entry.

Webhook HTTP Request

• HTTP Method: POST
• Content Type: application/json
• The HMAC signature is stored in the HTTP header: X-Miniflux-Signature.
• The event type is stored in the HTTP header X-Miniflux-Event-Type in addition to the request body.
• The body contains a JSON payload.

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 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

• Miniflux does not retry webhook events on request failures.