Webhooks

Les webhooks permettent à Metrrik d'envoyer un événement vers l'URL de votre choix (Zapier, Make, n8n, Power Automate ou votre propre serveur) dès qu'une action se produit dans votre espace : document approuvé, dépôt reçu, etc.

Configuration

Plan Avancé requis.

Réglages → Intégrations → Webhook.

Collez votre URL de destination (HTTPS uniquement, hôte public).

Cochez les événements à recevoir — ou laissez tout décoché pour les recevoir tous.

Connecter. Un secret de signature s'affiche une seule fois : copiez-le (il sert à vérifier l'authenticité des requêtes). Vous pouvez le régénérer à tout moment.

Tester envoie un événement webhook_test immédiat vers votre URL.

Requête

Chaque livraison est un POST JSON :

En-tête	Valeur
`Content-Type`	`application/json`
`User-Agent`	`Metrrik-Webhook/1`
`X-Metrrik-Event`	le type d'événement (ex. `document_signed`)
`X-Metrrik-Delivery`	identifiant unique de la livraison (UUID)
`X-Metrrik-Signature`	`sha256=<hmac hexadécimal du corps brut>`

Corps (contrat stable)

{
  "id": "9f1c…",                      // = X-Metrrik-Delivery, pour déduplication
  "event": "document_signed",
  "company_id": "…",
  "occurred_at": "2026-06-27T14:32:10.000Z",
  "data": {
    "title": "Facture #1043 approuvée",
    "body": "Le document a été approuvé par Marie Tremblay.",
    "link": "https://app.metrrik.com/acme/documents/1043"
  }
}

data.link est une URL absolue ou null. Le reste des champs est toujours présent.

Types d'événements

`event`	Déclencheur
`document_to_sign`	Un document attend votre approbation
`document_signed`	Un document a été approuvé
`document_rejected`	Un document a été rejeté
`comment_added`	Un commentaire a été ajouté
`new_inbox_email`	Un courriel est arrivé dans une boîte de réception
`new_deposit`	Un nouveau dépôt a été reçu
`category_delegated`	Une catégorie vous a été déléguée
`webhook_test`	Événement de test (bouton « Tester »)

Vérifier la signature

La signature est le HMAC-SHA256 du corps brut (avant tout parsing JSON), encodé en hexadécimal, préfixé de sha256=. Comparez-la en temps constant à celle que vous recalculez avec votre secret.

Node.js (Express)

import crypto from 'crypto'

function verifyMetrrikSignature(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(header || '')
  const b = Buffer.from(expected)
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

// Express : utilisez le corps BRUT, pas l'objet déjà parsé.
app.post('/webhooks/metrrik', express.raw({ type: 'application/json' }), (req, res) => {
  const ok = verifyMetrrikSignature(req.body, req.get('X-Metrrik-Signature'), process.env.METRRIK_WEBHOOK_SECRET)
  if (!ok) return res.status(401).end()
  const payload = JSON.parse(req.body.toString('utf8'))
  // … traiter payload.event …
  res.status(200).end()
})

PHP

$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('METRRIK_WEBHOOK_SECRET'));
$header = $_SERVER['HTTP_X_METRRIK_SIGNATURE'] ?? '';
if (!hash_equals($expected, $header)) { http_response_code(401); exit; }
$payload = json_decode($raw, true);

Bonnes pratiques

Idempotence : un même événement peut, dans de rares cas, être livré deux fois. Dédupliquez sur id (X-Metrrik-Delivery).
Répondez vite : renvoyez 2xx rapidement et traitez en arrière-plan. Metrrik abandonne après 5 secondes.
HTTPS public obligatoire : les URL en HTTP, vers localhost, une IP privée ou un domaine interne sont refusées (protection SSRF), à l'enregistrement comme à l'envoi.

Limites (v1)

Livraison best-effort, sans réessai. Si votre endpoint est indisponible ou répond une erreur, l'événement est perdu (journalisé côté Metrrik, pas rejoué). Un mécanisme de file d'attente avec réessais/backoff et journal de livraison pourra être ajouté ultérieurement.

Un seul webhook par entreprise.
La signature couvre le corps ; elle n'inclut pas d'horodatage anti-rejeu dédié (utilisez occurred_at / id si vous voulez fenêtrer les rejeux).