Merge pull request #2405 from kanishka0411/feat/custom-http-notifications

feat: custom http notifications

Author: KoalaSat

api/admin.py

@@ -504,6 +504,7 @@ class UserRobotAdmin(AdminChangeLinksMixin, admin.ModelAdmin):
         "id",
         "user_link",
         "telegram_enabled",
+        "webhook_enabled",
         "total_contracts",
         "earned_rewards",
         "claimed_rewards",

api/migrations/0056_robot_webhook_fields.py

@@ -0,0 +1,20 @@
+
+from django.db import migrations, models
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('api', '0055_order_description'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='robot',
+            name='webhook_url',
+            field=models.URLField(blank=True, max_length=500, null=True),
+        ),
+        migrations.AddField(
+            model_name='robot',
+            name='webhook_api_key',
+            field=models.CharField(blank=True, max_length=256, null=True),
+        ),
+    ]

api/migrations/0057_robot_webhook_enabled_alter_order_escrow_duration.py

@@ -0,0 +1,24 @@
+
+
+import django.core.validators
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('api', '0056_robot_webhook_fields'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='robot',
+            name='webhook_enabled',
+            field=models.BooleanField(default=False),
+        ),
+        migrations.AlterField(
+            model_name='order',
+            name='escrow_duration',
+            field=models.PositiveBigIntegerField(default=10799, validators=[django.core.validators.MinValueValidator(1800), django.core.validators.MaxValueValidator(36000)]),
+        ),
+    ]

api/models/robot.py

@@ -45,6 +45,10 @@ class Robot(models.Model):
     # nostr
     nostr_pubkey = models.CharField(max_length=64, null=True, blank=True)
 
+    webhook_url = models.URLField(max_length=500, null=True, blank=True)
+    webhook_api_key = models.CharField(max_length=256, null=True, blank=True)
+    webhook_enabled = models.BooleanField(default=False, null=False)
+
     # Claimable rewards
     earned_rewards = models.PositiveIntegerField(null=False, default=0)
     # Total claimed rewards
@@ -87,5 +91,19 @@ def create_user_robot(sender, instance, created, **kwargs):
     def save_user_robot(sender, instance, **kwargs):
         instance.robot.save()
 
+    @staticmethod
+    def is_valid_onion_url(url):
+        """Validates that the URL is a .onion address (Tor only)"""
+        if not url:
+            return False
+        try:
+            from urllib.parse import urlparse
+
+            parsed = urlparse(url)
+            hostname = parsed.hostname or ""
+            return hostname.endswith(".onion")
+        except Exception:
+            return False
+
     def __str__(self):
         return self.user.username

api/notifications.py

@@ -1,3 +1,7 @@
+import json
+import logging
+import uuid
+from datetime import datetime, timezone
 from secrets import token_urlsafe
 
 from decouple import config
@@ -8,6 +12,8 @@
 from api.utils import get_session
 from api.tasks import nostr_send_notification_event
 
+logger = logging.getLogger("api.notifications")
+
 
 class Notifications:
     """Simple telegram messages using TG's API"""
@@ -16,7 +22,7 @@ class Notifications:
     site = config("HOST_NAME")
 
     def get_context(user):
-        """returns context needed to enable TG notifications"""
+        """returns context needed to enable TG and webhook notifications"""
         context = {}
         if user.robot.telegram_enabled:
             context["tg_enabled"] = True
@@ -30,17 +36,24 @@ def get_context(user):
         context["tg_token"] = user.robot.telegram_token
         context["tg_bot_name"] = config("TELEGRAM_BOT_NAME")
 
+        context["webhook_enabled"] = user.robot.webhook_enabled
+        context["webhook_url"] = user.robot.webhook_url or ""
+
         return context
 
-    def send_message(self, order, robot, title, description=""):
-        """Save a message for a user and sends it to Telegram and/or Nostr"""
+    def send_message(
+        self, order, robot, title, description="", event_type="notification"
+    ):
+        """Save a message for a user and sends it to Telegram, Nostr, and/or Webhook"""
         self.save_message(order, robot, title, description)
         if robot.nostr_pubkey:
             nostr_send_notification_event.delay(
                 robot_id=robot.id, order_id=order.id, text=title
             )
         if robot.telegram_enabled:
             self.send_telegram_message(robot.telegram_chat_id, title, description)
+        if robot.webhook_enabled:
+            self.send_webhook_message(order, robot, title, description, event_type)
 
     def save_message(self, order, robot, title, description=""):
         """Save a message for a user"""
@@ -62,6 +75,104 @@ def send_telegram_message(self, chat_id, title, description=""):
             except Exception:
                 pass
 
+    def send_webhook_message(
+        self, order, robot, title, description="", event_type="notification"
+    ):
+        """Sends a webhook notification to the user's custom HTTP endpoint (Tor .onion only)"""
+        from api.models import Robot
+
+        webhook_url = robot.webhook_url
+        if not Robot.is_valid_onion_url(webhook_url):
+            logger.warning(
+                f"Webhook URL rejected: not a .onion address for robot {robot.id}"
+            )
+            return
+        payload = {
+            "event_type": event_type,
+            "event_id": str(uuid.uuid4()),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "robot_hash_id": robot.hash_id,
+            "order": {
+                "id": order.id,
+                "type": "BUY" if order.type == Order.Types.BUY else "SELL",
+                "status": order.status,
+            },
+            "message": {
+                "title": title,
+                "description": description,
+            },
+            "metadata": {
+                "coordinator": config("COORDINATOR_ALIAS", cast=str, default="Unknown"),
+                "platform_version": config("VERSION", cast=str, default="Unknown"),
+            },
+        }
+
+        headers = {
+            "Content-Type": "application/json",
+        }
+
+        if robot.webhook_api_key:
+            headers["X-API-Key"] = robot.webhook_api_key
+
+        try:
+            response = self.session.post(
+                webhook_url,
+                data=json.dumps(payload),
+                headers=headers,
+                timeout=60,
+            )
+            response.raise_for_status()
+            logger.info(f"Webhook sent successfully to robot {robot.id}")
+        except Exception as e:
+            logger.error(f"Webhook failed for robot {robot.id}: {e}")
+
+    def send_webhook_test(self, robot):
+        """Sends a test webhook notification when webhook is first configured"""
+        from api.models import Robot
+
+        webhook_url = robot.webhook_url
+        if not Robot.is_valid_onion_url(webhook_url):
+            logger.warning(
+                f"Webhook test rejected: not a .onion address for robot {robot.id}"
+            )
+            return False
+
+        payload = {
+            "event_type": "webhook_test",
+            "event_id": str(uuid.uuid4()),
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "robot_hash_id": robot.hash_id,
+            "message": {
+                "title": f"🔔 Hey {robot.user.username}, your webhook is configured!",
+                "description": "You will receive notifications about your RoboSats orders.",
+            },
+            "metadata": {
+                "coordinator": config("COORDINATOR_ALIAS", cast=str, default="Unknown"),
+                "platform_version": config("VERSION", cast=str, default="Unknown"),
+            },
+        }
+
+        headers = {
+            "Content-Type": "application/json",
+        }
+
+        if robot.webhook_api_key:
+            headers["X-API-Key"] = robot.webhook_api_key
+
+        try:
+            response = self.session.post(
+                webhook_url,
+                data=json.dumps(payload),
+                headers=headers,
+                timeout=60,
+            )
+            response.raise_for_status()
+            logger.info(f"Webhook test sent successfully to robot {robot.id}")
+            return True
+        except Exception as e:
+            logger.error(f"Webhook test failed for robot {robot.id}: {e}")
+            return False
+
     def welcome(self, user):
         """User enabled Telegram Notifications"""
         lang = user.robot.telegram_lang_code

api/oas_schemas.py

@@ -544,6 +544,21 @@ class RobotViewSchema:
                         "nullable": True,
                         "description": "Last time the coordinator saw this robot",
                     },
+                    "webhook_url": {
+                        "type": "string",
+                        "nullable": True,
+                        "description": "Webhook URL for custom notifications (.onion only)",
+                    },
+                    "webhook_enabled": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": "Whether webhook notifications are enabled",
+                    },
+                    "webhook_api_key": {
+                        "type": "string",
+                        "nullable": True,
+                        "description": "API key sent in X-API-Key header for webhook authentication",
+                    },
                 },
             },
         },
@@ -555,9 +570,85 @@ class RobotViewSchema:
                     "public_key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\n\n......\n......",
                     "encrypted_private_key": "-----BEGIN PGP PRIVATE KEY BLOCK-----\n\n......\n......",
                     "wants_stealth": True,
+                    "webhook_enabled": False,
+                    "webhook_url": None,
+                },
+                status_codes=[200],
+            ),
+        ],
+    }
+
+    put = {
+        "summary": "Update robot webhook settings",
+        "description": textwrap.dedent(
+            """
+            Update the robot's webhook notification settings.
+
+            Webhooks allow you to receive HTTP POST notifications to your own server
+            when order events occur. **Only `.onion` URLs are accepted** for privacy.
+
+            The webhook payload contains:
+            - `event`: Type of notification (e.g., "order_taken", "escrow_locked")
+            - `order_id`: The order ID related to the notification
+            - `message`: Human-readable notification message
+            - `robot`: Robot nickname
+            - `coordinator`: Coordinator short alias
+            - `timestamp`: ISO format timestamp
+
+            If `webhook_api_key` is set, it will be sent in the `X-API-Key` header.
+
+            **Note:** Webhook is enabled automatically when a valid .onion URL is set.
+            A test notification will be sent when the webhook URL is configured.
+            """
+        ),
+        "responses": {
+            200: {
+                "type": "object",
+                "properties": {
+                    "webhook_url": {
+                        "type": "string",
+                        "nullable": True,
+                        "description": "Webhook URL (.onion only)",
+                    },
+                    "webhook_enabled": {
+                        "type": "boolean",
+                        "description": "Whether webhook notifications are enabled",
+                    },
+                    "webhook_api_key": {
+                        "type": "string",
+                        "nullable": True,
+                        "description": "API key sent in X-API-Key header",
+                    },
+                },
+            },
+            400: {
+                "type": "object",
+                "properties": {
+                    "webhook_url": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Validation errors for webhook_url field",
+                    },
+                },
+            },
+        },
+        "examples": [
+            OpenApiExample(
+                "Successfully updated webhook settings",
+                value={
+                    "webhook_url": "http://myserver.onion/webhook",
+                    "webhook_enabled": True,
+                    "webhook_api_key": "my-secret-key",
                 },
                 status_codes=[200],
             ),
+            OpenApiExample(
+                "Invalid URL (not .onion)",
+                value={
+                    "webhook_url": ["Webhook URL must be a Tor .onion address"],
+                },
+                status_codes=[400],
+            ),
         ],
     }