[webhooks] add getting started for webhooks

docs/getting-started/local-server.md

@@ -18,5 +18,8 @@ This mode is ideal for sending messages from a local network.
 5. To send a message from within the local network, execute a `curl` command like the following. Be sure to replace `<username>`, `<password>`, and `<device_local_ip>` with the actual values provided in the previous step:
 
     ```sh
-    curl -X POST -u <username>:<password> -H "Content-Type: application/json" -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' http://<device_local_ip>:8080/message
+    curl -X POST -u <username>:<password> \
+        -H "Content-Type: application/json" \
+        -d '{ "message": "Hello, world!", "phoneNumbers": ["+79990001234", "+79995556677"] }' \
+        http://<device_local_ip>:8080/message
     ```

docs/getting-started/private-server.md

@@ -21,7 +21,8 @@ To enhance privacy, you can host a private server within your own infrastructure
    - Define `gateway.private_token` as the access token for device registration in private mode. Ensure this token matches the one on the devices set to private mode.
 2. Start the server in Docker with the following command: 
    ```sh
-   docker run -p 3000:3000 -v $(pwd)/config.yml:/app/config.yml capcom6/sms-gateway:latest
+   docker run -p 3000:3000 -v $(pwd)/config.yml:/app/config.yml \
+    capcom6/sms-gateway:latest
    ```
 3. Configure your reverse proxy, enable SSL, and modify your firewall settings to permit Internet access to the server.
 

docs/getting-started/public-cloud-server.md

@@ -18,5 +18,8 @@ Use the cloud server mode when dealing with dynamic or shared device IP addresse
 5. To send a message via the cloud server, perform a `curl` request with a command similar to the following, substituting `<username>` and `<password>` with the actual values obtained in step 4:
 
     ```sh
-    curl -X POST -u <username>:<password> -H "Content-Type: application/json" -d '{ "message": "Hello, world!", "phoneNumbers": ["79990001234", "79995556677"] }' https://sms.capcom.me/api/3rdparty/v1/message
+    curl -X POST -u <username>:<password> \
+      -H "Content-Type: application/json" \
+      -d '{ "message": "Hello, world!", "phoneNumbers": ["+79990001234", "+79995556677"] }' \
+      https://sms.capcom.me/api/3rdparty/v1/message
     ```

docs/getting-started/webhooks.md

@@ -0,0 +1,40 @@
+# Getting Started
+
+## Webhooks
+
+Webhooks can be utilized to get notifications of incoming SMS messages.
+
+Follow these steps to set up webhooks:
+
+1. Set up your own HTTP server with a valid SSL certificate to receive webhooks. For testing purposes, [webhook.site](https://webhook.site) can be useful.
+2. Register your webhook with an API request:
+
+    ```sh
+    curl -X POST -u <username>:<password> \
+      -H "Content-Type: application/json" \
+      -d '{ "id": "unique-id", "url": "https://webhook.site/<your-uuid>", "event": "sms:received" }' \
+      http://<device_local_ip>:8080/webhooks
+    ```
+
+3. Send an SMS to the device.
+4. The application will dispatch POST request to the specified URL with a payload such as:
+
+    ```json
+    {
+      "event": "sms:received",
+      "payload": {
+        "message": "Received SMS text",
+        "phoneNumber": "+79990001234",
+        "receivedAt": "2024-06-07T11:41:31.000+07:00"
+      }
+    }
+    ```
+
+5. To deregister a webhook, execute a `curl` request using the following pattern:
+
+    ```sh
+    curl -X DELETE -u <username>:<password> \
+      http://<device_local_ip>:8080/webhooks/unique-id
+    ```
+
+*Note*: Webhooks are transmitted directly from the device; therefore, the device must have an outgoing internet connection. As the requests originate from the device, incoming messages remain inaccessible to us.

docs/index.md

@@ -4,7 +4,7 @@
     <img src="/assets/logo.png" alt="Logo">
 </div>
 
-Android SMS Gateway turns your Android smartphone into an SMS gateway. It's a lightweight application that allows you to send SMS messages programmatically via an API. This makes it ideal for integrating SMS functionality into your own applications or services.
+Android SMS Gateway turns your Android smartphone into an SMS gateway. It's a lightweight application that allows you to send SMS messages programmatically via an API and receive webhooks on incoming SMS. This makes it ideal for integrating SMS functionality into your own applications or services.
 
 <p align="center"><img src="/assets/screenshot.png" width="360"></p>
 
@@ -21,14 +21,16 @@ Android SMS Gateway turns your Android smartphone into an SMS gateway. It's a li
 - **Message expiration:** The application allows setting an expiration time for messages. Messages will not be sent if they have expired.
 - **Random delay between messages:** Introduces a random delay between sending messages to avoid mobile operator restrictions.
 - **Private server support:** The application allows for the use of a backend server in the user's infrastructure for enhanced security.
+- **Webhooks on incoming SMS:** The application allows setting up webhooks to be sent to a specified URL whenever an SMS is received.
 
 ## Ideal For
 
 - Notifications
 - Alerts
 - Two-factor authentication codes
+- Receiving incoming SMS
 
-Android SMS Gateway offers a convenient and reliable solution for sending notifications, alerts, or two-factor authentication codes.
+Android SMS Gateway offers a convenient and reliable solution for sending notifications, alerts, or two-factor authentication codes, and also allows you to receive webhooks when an SMS is received.
 
 *Note*: It is not recommended to use this for batch sending due to potential mobile operator restrictions.
 

mkdocs.yml

@@ -35,6 +35,7 @@ nav:
       - Public Cloud Server: getting-started/public-cloud-server.md
       - Private Server: getting-started/private-server.md
       - Custom Gateway Setup: getting-started/custom-gateway.md
+      - Webhooks: getting-started/webhooks.md
   - Integration:
       - API: integration/api.md
   - Pricing: pricing.md
@@ -61,3 +62,11 @@ plugins:
         remove_comments: true
       cache_safe: true
   - social
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences