✨(teams) add matrix webhook for teams

A webhook to invite/kick team members to a matrix room.

Author: mjeammet

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to
 
 ### Added
 
+- ✨(teams) add matrix webhook for teams #904
 - ✨(resource-server) add SCIM /Me endpoint #895
 - 🔧(git) set LF line endings for all text files #928
 

src/backend/core/enums.py

@@ -24,3 +24,10 @@ class WebhookStatusChoices(models.TextChoices):
     FAILURE = "failure", _("Failure")
     PENDING = "pending", _("Pending")
     SUCCESS = "success", _("Success")
+
+
+class WebhookProtocolChoices(models.TextChoices):
+    """Defines the possible protocols of webhook."""
+
+    SCIM = "scim"
+    MATRIX = "matrix"

src/backend/core/migrations/0017_teamwebhook_protocol.py

@@ -0,0 +1,18 @@
+# Generated by Django 5.2.3 on 2025-06-17 14:23
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('core', '0016_team_external_id_alter_team_users'),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name='teamwebhook',
+            name='protocol',
+            field=models.CharField(choices=[('scim', 'Scim'), ('matrix', 'Matrix')], default='scim'),
+        ),
+    ]

src/backend/core/models.py

@@ -21,7 +21,7 @@
 from django.contrib.sites.models import Site
 from django.core import exceptions, mail, validators
 from django.core.exceptions import ValidationError
-from django.db import models, transaction
+from django.db import models
 from django.template.loader import render_to_string
 from django.utils import timezone
 from django.utils.translation import gettext, override
@@ -31,9 +31,9 @@
 from timezone_field import TimeZoneField
 from treebeard.mp_tree import MP_Node, MP_NodeManager
 
-from core.enums import WebhookStatusChoices
+from core.enums import WebhookProtocolChoices, WebhookStatusChoices
 from core.plugins.registry import registry as plugin_hooks_registry
-from core.utils.webhooks import scim_synchronizer
+from core.utils.webhooks import webhooks_synchronizer
 from core.validators import get_field_validators_from_setting
 
 logger = getLogger(__name__)
@@ -864,28 +864,25 @@ def save(self, *args, **kwargs):
         Override save function to fire webhooks on any addition or update
         to a team access.
         """
-
-        if self._state.adding:
+        if self._state.adding and self.team.webhooks.exists():
             self.team.webhooks.update(status=WebhookStatusChoices.PENDING)
-            with transaction.atomic():
-                instance = super().save(*args, **kwargs)
-                scim_synchronizer.add_user_to_group(self.team, self.user)
-        else:
-            instance = super().save(*args, **kwargs)
+            # try to synchronize all webhooks
+            webhooks_synchronizer.add_user_to_group(self.team, self.user)
 
-        return instance
+        return super().save(*args, **kwargs)
 
     def delete(self, *args, **kwargs):
         """
         Override delete method to fire webhooks on  to team accesses.
         Don't allow deleting a team access until it is successfully synchronized with all
         its webhooks.
         """
-        self.team.webhooks.update(status=WebhookStatusChoices.PENDING)
-        with transaction.atomic():
-            arguments = self.team, self.user
-            super().delete(*args, **kwargs)
-            scim_synchronizer.remove_user_from_group(*arguments)
+        if webhooks := self.team.webhooks.all():
+            webhooks.update(status=WebhookStatusChoices.PENDING)
+            # try to synchronize all webhooks
+            webhooks_synchronizer.remove_user_from_group(self.team, self.user)
+
+        super().delete(*args, **kwargs)
 
     def get_abilities(self, user):
         """
@@ -943,6 +940,11 @@ class TeamWebhook(BaseModel):
     team = models.ForeignKey(Team, related_name="webhooks", on_delete=models.CASCADE)
     url = models.URLField(_("url"))
     secret = models.CharField(_("secret"), max_length=255, null=True, blank=True)
+    protocol = models.CharField(
+        max_length=None,
+        default=WebhookProtocolChoices.SCIM,
+        choices=WebhookProtocolChoices.choices,
+    )
     status = models.CharField(
         max_length=10,
         default=WebhookStatusChoices.PENDING,

src/backend/core/tests/fixtures/__init__.py

@@ -0,0 +1 @@
+"""Test fixtures."""

src/backend/core/tests/fixtures/matrix.py

@@ -0,0 +1,75 @@
+"""Define here some fake responses from Matrix API, useful to mock responses in tests."""
+
+from rest_framework import status
+
+
+# JOIN ROOMS
+def mock_join_room_successful(room_id):
+    """Mock response when succesfully joining room. Same response if already in room."""
+    return {"message": {"room_id": str(room_id)}, "status_code": status.HTTP_200_OK}
+
+
+def mock_join_room_no_known_servers():
+    """Mock response when room to join cannot be found."""
+    return {
+        "message": {"errcode": "M_UNKNOWN", "error": "No known servers"},
+        "status_code": status.HTTP_404_NOT_FOUND,
+    }
+
+
+def mock_join_room_forbidden():
+    """Mock response when room cannot be joined."""
+    return {
+        "message": {
+            "errcode": "M_FORBIDDEN",
+            "error": "You do not belong to any of the required rooms/spaces to join this room.",
+        },
+        "status_code": status.HTTP_403_FORBIDDEN,
+    }
+
+
+# INVITE USER
+def mock_invite_successful():
+    """Mock response when invite request was succesful. Does not check the user exists."""
+    return {"message": {}, "status_code": status.HTTP_200_OK}
+
+
+def mock_invite_user_already_in_room(user):
+    """Mock response when invitation forbidden for People user."""
+    return {
+        "message": {
+            "errcode": "M_FORBIDDEN",
+            "error": f"{user.email.replace('@', ':')} is already in the room.",
+        },
+        "status_code": status.HTTP_403_FORBIDDEN,
+    }
+
+
+# KICK USER
+def mock_kick_successful():
+    """Mock response when succesfully joining room."""
+    return {"message": {}, "status_code": status.HTTP_200_OK}
+
+
+def mock_kick_user_forbidden(user):
+    """Mock response when kick request is forbidden (i.e. wrong permission or user is room admin."""
+    return {
+        "message": {
+            "errcode": "M_FORBIDDEN",
+            "error": f"You cannot kick user @{user.email.replace('@', ':')}.",
+        },
+        "status_code": status.HTTP_403_FORBIDDEN,
+    }
+
+
+def mock_kick_user_not_in_room():
+    """
+    Mock response when trying to kick a user who isn't in the room. Don't check the user exists.
+    """
+    return {
+        "message": {
+            "errcode": "M_FORBIDDEN",
+            "error": "The target user is not in the room",
+        },
+        "status_code": status.HTTP_403_FORBIDDEN,
+    }

src/backend/core/tests/team_accesses/test_api_team_accesses_create.py

@@ -3,14 +3,17 @@
 """
 
 import json
+import logging
 import random
 import re
 
 import pytest
 import responses
+from rest_framework import status
 from rest_framework.test import APIClient
 
-from core import factories, models
+from core import enums, factories, models
+from core.tests.fixtures import matrix
 
 pytestmark = pytest.mark.django_db
 
@@ -171,14 +174,17 @@ def test_api_team_accesses_create_authenticated_owner():
     }
 
 
-def test_api_team_accesses_create_webhook():
+def test_api_team_accesses_create__with_scim_webhook():
     """
-    When the team has a webhook, creating a team access should fire a call.
+    If a team has a SCIM webhook, creating a team access should fire a call
+    with the expected payload.
     """
     user, other_user = factories.UserFactory.create_batch(2)
 
     team = factories.TeamFactory(users=[(user, "owner")])
-    webhook = factories.TeamWebhookFactory(team=team)
+    webhook = factories.TeamWebhookFactory(
+        team=team, protocol=enums.WebhookProtocolChoices.SCIM
+    )
 
     role = random.choice([role[0] for role in models.RoleChoices.choices])
 
@@ -226,3 +232,139 @@ def test_api_team_accesses_create_webhook():
                 }
             ],
         }
+
+    assert models.TeamAccess.objects.filter(user=other_user, team=team).exists()
+
+
+def test_api_team_accesses_create__multiple_webhooks_success(caplog):
+    """
+    When the team has multiple webhooks, creating a team access should fire all the expected calls.
+    If all responses are positive, proceeds to add the user to the team.
+    """
+    caplog.set_level(logging.INFO)
+
+    user, other_user = factories.UserFactory.create_batch(2)
+
+    team = factories.TeamFactory(users=[(user, "owner")])
+    webhook_scim = factories.TeamWebhookFactory(
+        team=team, protocol=enums.WebhookProtocolChoices.SCIM, secret="wesh"
+    )
+    webhook_matrix = factories.TeamWebhookFactory(
+        team=team,
+        url="https://www.webhookserver.fr/#/room/room_id:home_server/",
+        protocol=enums.WebhookProtocolChoices.MATRIX,
+        secret="yo",
+    )
+
+    role = random.choice([role[0] for role in models.RoleChoices.choices])
+
+    client = APIClient()
+    client.force_login(user)
+
+    with responses.RequestsMock() as rsps:
+        # Ensure successful response by scim provider using "responses":
+        rsps.add(
+            rsps.PATCH,
+            re.compile(r".*/Groups/.*"),
+            body="{}",
+            status=200,
+            content_type="application/json",
+        )
+        rsps.add(
+            rsps.POST,
+            re.compile(r".*/join"),
+            body=str(matrix.mock_join_room_successful),
+            status=status.HTTP_200_OK,
+            content_type="application/json",
+        )
+        rsps.add(
+            rsps.POST,
+            re.compile(r".*/invite"),
+            body=str(matrix.mock_invite_successful()["message"]),
+            status=matrix.mock_invite_successful()["status_code"],
+            content_type="application/json",
+        )
+
+        response = client.post(
+            f"/api/v1.0/teams/{team.id!s}/accesses/",
+            {
+                "user": str(other_user.id),
+                "role": role,
+            },
+            format="json",
+        )
+        assert response.status_code == 201
+
+    # Logger
+    log_messages = [msg.message for msg in caplog.records]
+    for webhook in [webhook_scim, webhook_matrix]:
+        assert (
+            f"add_user_to_group synchronization succeeded with {webhook.url}"
+            in log_messages
+        )
+
+    # Status
+    for webhook in [webhook_scim, webhook_matrix]:
+        webhook.refresh_from_db()
+        assert webhook.status == "success"
+    assert models.TeamAccess.objects.filter(user=other_user, team=team).exists()
+
+
+@responses.activate
+def test_api_team_accesses_create__multiple_webhooks_failure(caplog):
+    """When a webhook fails, user should still be added to the team."""
+    caplog.set_level(logging.INFO)
+
+    user, other_user = factories.UserFactory.create_batch(2)
+
+    team = factories.TeamFactory(users=[(user, "owner")])
+    webhook_scim = factories.TeamWebhookFactory(
+        team=team, protocol=enums.WebhookProtocolChoices.SCIM, secret="wesh"
+    )
+    webhook_matrix = factories.TeamWebhookFactory(
+        team=team,
+        url="https://www.webhookserver.fr/#/room/room_id:home_server/",
+        protocol=enums.WebhookProtocolChoices.MATRIX,
+        secret="secret",
+    )
+
+    role = random.choice([role[0] for role in models.RoleChoices.choices])
+    client = APIClient()
+    client.force_login(user)
+
+    responses.patch(
+        re.compile(r".*/Groups/.*"),
+        body="{}",
+        status=200,
+    )
+    responses.post(
+        re.compile(r".*/join"),
+        body=str(matrix.mock_join_room_forbidden()["message"]),
+        status=str(matrix.mock_join_room_forbidden()["status_code"]),
+    )
+
+    response = client.post(
+        f"/api/v1.0/teams/{team.id!s}/accesses/",
+        {
+            "user": str(other_user.id),
+            "role": role,
+        },
+        format="json",
+    )
+    assert response.status_code == status.HTTP_201_CREATED
+
+    # Logger
+    log_messages = [msg.message for msg in caplog.records]
+    assert (
+        f"add_user_to_group synchronization succeeded with {webhook_scim.url}"
+        in log_messages
+    )
+    assert (
+        f"add_user_to_group synchronization failed with {webhook_matrix.url}"
+        in log_messages
+    )
+
+    # Status
+    webhook_scim.status = "success"
+    webhook_matrix.status = "failure"
+    assert models.TeamAccess.objects.filter(user=other_user, team=team).exists()