Webhooks

MCM peut envoyer des notifications webhook à votre application lorsque certains événements se produisent.

Vue d'ensemble

Le système de webhooks MCM permet de recevoir des notifications en temps réel. Quand un événement est déclenché, MCM envoie une requête HTTP POST à l'URL configurée avec les détails de l'événement.

Configuration

1. Obtenir le secret

Un administrateur système MCM configure l'URL webhook et les événements dans le tableau de bord MCM. Un secret unique est généré — communiquez-le à votre équipe de manière sécurisée.

2. Installer le package

dotnet add package MCM.ApiProxy
dotnet add package MCM.B2B.Contracts

3. Configurer le récepteur

Dans appsettings.json:

{
  "McmApi": {
    "WebhookSecret": "votre-secret-ici"
  }
}

Dans Program.cs:

using MCM.ApiProxy.Webhooks;
using MCM.B2B.Contracts.Webhooks;

// Enregistrer le récepteur et les handlers
builder.Services.AddMcmWebhookReceiver(builder.Configuration)
    .AddHandler<ListeElectoraleHandler, B2BListeElectoraleCreeData>(
        WebhookEventTypes.ListeElectoraleCree);

var app = builder.Build();

// Mapper l'endpoint webhook
app.MapMcmWebhooks("/webhooks/mcm");

Écrire un handler

Chaque handler traite un type d'événement spécifique. Le middleware s'occupe de la validation de signature et de la désérialisation.

using MCM.B2B.Contracts.Webhooks;

public class ListeElectoraleHandler : IMcmWebhookHandler<B2BListeElectoraleCreeData>
{
    private readonly ILogger<ListeElectoraleHandler> _logger;

    public ListeElectoraleHandler(ILogger<ListeElectoraleHandler> logger)
    {
        _logger = logger;
    }

    public async Task HandleAsync(
        B2BWebhookPayload<B2BListeElectoraleCreeData> payload,
        CancellationToken ct)
    {
        _logger.LogInformation(
            "Liste électorale créée pour la campagne {CampagneId}: {Count} votants ajoutés",
            payload.Data.CampagneId,
            payload.Data.NombreVotantsAjoutes);

        // Votre logique métier ici
    }
}

Événements disponibles

Type d'événement	Description	Données
campagne.liste_electorale_cree	Liste électorale créée après ajout en lot	B2BListeElectoraleCreeData

Sécurité

Signature HMAC-SHA256

Chaque webhook est signé avec votre secret. Le middleware valide automatiquement:

En-tête	Description
X-MCM-Signature	sha256=<hex> — HMAC-SHA256 de {timestamp}.{body}
X-MCM-Timestamp	Timestamp Unix (protection contre le rejeu)
X-MCM-Delivery-Id	GUID unique (idempotence)
X-MCM-Event	Type d'événement

Validation manuelle

Si vous n'utilisez pas le middleware MCM, validez manuellement:

using MCM.B2B.Contracts.Webhooks;

string signature = request.Headers["X-MCM-Signature"];
string timestamp = request.Headers["X-MCM-Timestamp"];
string body = await new StreamReader(request.Body).ReadToEndAsync();

bool isValid = WebhookSignatureValidator.IsValid(
    secret, timestamp, body, signature);

Tentatives de livraison

MCM réessaie la livraison en cas d'échec:

• 5 tentatives avec délais croissants: 30s, 1min, 5min, 15min, 1h
• Codes HTTP 2xx = succès
• Après 3 échecs consécutifs complets, l'abonnement est automatiquement désactivé

Bonnes pratiques

1. Répondez rapidement — Retournez un 200 OK dès que possible, traitez en arrière-plan si nécessaire
2. Idempotence — Utilisez le DeliveryId pour éviter de traiter un événement deux fois
3. Vérifiez la signature — Ne traitez jamais un webhook sans validation
4. Protégez votre secret — Ne le commitez pas dans votre code source