Menu

Référence des webhooks

Recevez les messages MailContact dans votre application ou automatisation. Disponible avec Pro et Plus.

Envie d’alertes email, Slack ou Discord ? Suivez le guide des notifications.

La charge utile

Chaque nouveau message déclenche un POST HTTP vers votre URL avec un Content-Type: application/json body:

POST https://your-app.example/hooks/mailcontact
{
  "id": "d8f2e71a20b4",
  "event": "message.created",
  "project": {
    "id": "prj_8f2k1q",
    "name": "acme-site"
  },
  "source": {
    "type": "form",
    "name": "Website contact form"
  },
  "url": "https://mailcontact.app/app/projects/prj_8f2k1q?message=msg_4t9s2e",
  "reply": {
    "url": "https://mailcontact.app/app/projects/prj_8f2k1q?message=msg_4t9s2e",
    "method": "open_conversation"
  },
  "message": {
    "id": "msg_4t9s2e",
    "from": {
      "name": "Ada Lovelace",
      "email": "[email protected]"
    },
    "subject": "Question about pricing",
    "body": "Hi, quick question about the Pro plan...",
    "receivedAt": "2026-07-14T09:30:00.000Z"
  }
}

Champs

  • event: message.created pour un message reçu, ou notification.test pour le bouton Tester. Les événements de test ont un message et source.
  • project: le projet dont la boîte a reçu le message (son id et name).
  • source: l’origine du message. type est "form" (le point de réception de formulaire) ou "email" (le adresse email du projet); name est le libellé de la source dans votre boîte.
  • message.from: celui de l’expéditeur email (toujours présent) et name (peut être vide si l’expéditeur n’en a pas fourni).
  • message.subject: facultatif pour les envois de formulaire, il peut donc être vide.
  • message.receivedAt: horodatage ISO 8601, UTC.
  • reply.url: ouvre cette conversation dans Mailcontact, où son propriétaire peut répondre après connexion. Ce lien ne donne aucun accès à lui seul. Les événements de test ont un reply.

Livraison

  • Répondez vite. Renvoyez un statut 2xx dès l’acceptation et effectuez le travail réel en asynchrone. La livraison expire après 10 secondes.
  • Au moins une fois. Une réponse lente ou une erreur temporaire peut entraîner plusieurs livraisons du même message. Dédupliquez à l’aide du champ id, également envoyé dans le Idempotency-Key et X-Mailcontact-Event-Id en-têtes.
  • Les erreurs temporaires et HTTP 429 sont retentées jusqu’à cinq fois, avec des délais exponentiels. La plupart des autres réponses 4xx arrêtent la livraison.
  • Utilisez une URL HTTPS publique sur le port 443. Réseaux privés, identifiants dans l’URL et redirections sont refusés.

Sécurité

Les charges utiles ne sont pas encore signées : quiconque découvre l’URL du webhook peut y envoyer un faux POST. Suivez ces précautions :

  • Utilisez un chemin long et imprévisible pour le webhook sans le publier.
  • Traitez toute charge utile comme non fiable : validez avant d’agir.
  • Ne déclenchez aucune action destructive ou irréversible depuis un webhook non signé. Notifier, journaliser et mettre en attente convient ; supprimer des éléments, non.

La signature des webhooks n’est pas disponible actuellement. Recevoir une charge utile ne prouve pas son expéditeur.

Webhooks et canaux de notification

Utilisez le guide des notifications pour les alertes email, Slack et Discord. Cette référence présente le format générique des webhooks pour votre code. Voir tarifs pour les offres actuelles.