Update webhook docs

miniflux · Sep 11, 2023 · 17c9fbd · 17c9fbd
1 parent 89444ca
commit 17c9fbd
Showing 1 changed file with 116 additions and 50 deletions.
diff --git a/content/docs/webhooks.md b/content/docs/webhooks.md
@@ -18,63 +18,22 @@ Configuring a Webhook in Miniflux
 
 The auto-generated secret is used to validate the payload.
 
-Webhook Event Request
----------------------
+Webhook Event Types
+-------------------
 
-The HTTP requests sent by Miniflux are structured like this:
+Miniflux supports different types of event:
 
-```
-POST /your-webhook-endpoint HTTP/1.1
+- `new_entries`: Event sent during a feed refresh when new entries are discovered
+- `save_entry`: Event sent when the end-user save an entry
 
-Content-Type: application/json
-User-Agent: Miniflux/2.0.48
-X-Miniflux-Signature: 7ff170cfd8c173fd5084e0f51ee6ac3eae8acff443f11f9168961cebf836e38f
-
-{
-  "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"]
-        }
-    ]
-}
-```
+Webhook HTTP Request
+--------------------
 
 - HTTP Method: `POST`
 - Content Type: `application/json`
 - The HMAC signature is stored in the HTTP header: `X-Miniflux-Signature`
-- The body contains some information about the feed and a list of new entries
+- The event type in stored in HTTP header `X-Miniflux-Event-Type` in addition to the request body
+- The body contains a JSON payload
 
 Validating Signatures from Miniflux
 -----------------------------------
@@ -106,6 +65,113 @@ This allows you to password protect the webhook URLs on your web server so that
 
 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
 -----