Webhooks : suivre le statut DGI de vos factures

{
  "id": "3f6c2a9e-8d1b-4c7a-9e2f-1a2b3c4d5e6f",
  "type": "invoice.accepted",
  "apiVersion": "2026-07-01",
  "createdAt": "2026-09-30T14:05:12Z",
  "data": {
    "invoice": {
      "id": "b1e2c3d4-0000-4000-8000-000000000001",
      "invoiceNumber": "FAC-2026-0142",
      "status": "ACCEPTED",
      "previousStatus": "TRANSMITTED",
      "currency": "MAD",
      "amountTtc": 1200.00,
      "dgiReference": "DGI-REF-...",
      "dgiQrCode": "...",
      "errorCode": null,
      "errorMessage": null
    }
  }
}

POST /webhooks/efact HTTP/1.1
Content-Type: application/json
efact-webhook-id: 3f6c2a9e-8d1b-4c7a-9e2f-1a2b3c4d5e6f
efact-webhook-timestamp: 1790777112
efact-webhook-signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.EFACT_WEBHOOK_SECRET!;

function verifyEfactSignature(rawBody: Buffer, headers: express.Request["headers"]): boolean {
  const id = headers["efact-webhook-id"];
  const timestamp = headers["efact-webhook-timestamp"];
  const header = headers["efact-webhook-signature"];
  if (typeof id !== "string" || typeof timestamp !== "string" || typeof header !== "string") {
    return false;
  }
  // Anti-rejeu : 5 minutes de tolérance.
  const ts = Number(timestamp);
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;

  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest();
  // Une entrée "v1=" par secret valide (deux pendant une rotation).
  return header.split(",").some((entry) => {
    const [scheme, hex] = entry.trim().split("=");
    if (scheme !== "v1" || !hex) return false;
    const candidate = Buffer.from(hex, "hex");
    return candidate.length === expected.length && crypto.timingSafeEqual(candidate, expected);
  });
}

const app = express();

// Corps BRUT obligatoire : la signature porte sur les octets reçus.
app.post("/webhooks/efact", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyEfactSignature(req.body, req.headers)) return res.sendStatus(400);
  const event = JSON.parse(req.body.toString("utf8"));

  // Répondez 2xx tout de suite, traitez ensuite (file de jobs).
  res.sendStatus(200);
  queue.add("efact-event", event, { jobId: event.id }); // jobId = dédoublonnage
});

curl -X POST https://api.efact.ma/v1/webhooks \
  -H "Authorization: Bearer $EFACT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.example.ma/webhooks/efact",
    "description": "ERP production",
    "events": ["invoice.accepted", "invoice.rejected", "invoice.failed"]
  }'

{
  "code": "OK",
  "message": null,
  "data": {
    "id": "7c1d9b2e-4f3a-4e8b-9a6d-2b5c8e1f0a3d",
    "organizationId": "5e0b...",
    "url": "https://erp.example.ma/webhooks/efact",
    "description": "ERP production",
    "events": ["invoice.accepted", "invoice.rejected", "invoice.failed"],
    "active": true,
    "secret": "whsec_...",
    "createdAt": "2026-09-30T14:00:00Z",
    "previousSecretExpiresAt": null
  },
  "errors": null
}

# Tester le récepteur (réponse : { success, responseStatus, message })
curl -X POST https://api.efact.ma/v1/webhooks/$ENDPOINT_ID/test \
  -H "Authorization: Bearer $EFACT_SECRET_KEY"

# Désactiver temporairement
curl -X PATCH https://api.efact.ma/v1/webhooks/$ENDPOINT_ID \
  -H "Authorization: Bearer $EFACT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

# Changer le secret (data.secret, affiché une seule fois)
curl -X POST https://api.efact.ma/v1/webhooks/$ENDPOINT_ID/rotate-secret \
  -H "Authorization: Bearer $EFACT_SECRET_KEY"

# Consulter les dernières livraisons, puis en relancer une
curl "https://api.efact.ma/v1/webhooks/$ENDPOINT_ID/deliveries?page=0&size=20" \
  -H "Authorization: Bearer $EFACT_SECRET_KEY"
curl -X POST https://api.efact.ma/v1/webhooks/deliveries/$DELIVERY_ID/retry \
  -H "Authorization: Bearer $EFACT_SECRET_KEY"