mod_rest: Allow specifying a webhook/callback to handle incoming stanzas

author: Kim Alvefur <zash@zash.se>
date: Mon, 30 Dec 2019 04:07:25 +0100
parent: 3794:4b258329e6e4
child: 3796:d1ad10b76b00
--- a/mod_rest/README.markdown	Mon Dec 30 04:04:34 2019 +0100
+++ b/mod_rest/README.markdown	Mon Dec 30 04:07:25 2019 +0100
@@ -6,7 +6,9 @@
 
 # Introduction
 
-This is yet another RESTful API for sending stanzas via Prosody.
+This is yet another RESTful API for sending and receiving stanzas via
+Prosody. It can be used to build bots and components implemented as HTTP
+services.
 
 # Usage
 
@@ -49,6 +51,44 @@
         </iq>'
 ```
 
+## Receiving stanzas
+
+TL;DR: Set this webhook callback URL, get XML `POST`-ed there.
+
+``` {.lua}
+Component "rest.example.net" "rest"
+rest_callback_url = "http://my-api.example:9999/stanzas"
+```
+
+Example callback looks like:
+
+``` {.xml}
+POST /stanzas HTTP/1.1
+Content-Type: application/xmpp+xml
+Content-Length: 52
+
+<message to="bot@rest.example.net" from="user@example.com" type="chat">
+<body>Hello</body>
+</message>
+```
+
+### Replying
+
+To accept the stanza without returning a reply, respond with HTTP status
+code `202` or `204`.
+
+For full control over the response, set the `Content-Type` header to
+`application/xmpp+xml` and return an XMPP stanza as an XML snippet.
+
+``` {.xml}
+HTTP/1.1 200 Ok
+Content-Type: application/xmpp+xml
+
+<message type="chat">
+<body>Yes, this is bot</body>
+</message>
+```
+
 # Compatibility
 
 Requires Prosody trunk / 0.12