Webhooks
einvo calls your HTTPS endpoint when something happens to a document. Register endpoints in the portal (Administration → Webhooks) or with
POST /api/v1/webhooks (scope webhooks). The signing secret (whsec_…) is returned once.
Events
| Event | When |
|---|---|
document.received | A document from the Peppol network arrived in your inbox |
document.status | A document you sent changed status (validated, sent, delivered, rejected by the buyer…) |
document.fta | The FTA reporting of a document was accepted or refused |
curl https://api.einvo.ae/api/v1/webhooks -H "Authorization: Bearer $EINVO_API_KEY" -H "Content-Type: application/json" -d '{
"url": "https://erp.example.com/einvo/webhook",
"events": ["document.received", "document.status", "document.fta"],
"description": "ERP production"
}'
# {"endpoint":{"id":"...","url":"...","events":[...],"active":true},"secret":"whsec_..."}
curl -X POST https://api.einvo.ae/api/v1/webhooks/$ENDPOINT_ID/test -H "Authorization: Bearer $EINVO_API_KEY"
Request
POST /einvo/webhook HTTP/1.1
Content-Type: application/json
User-Agent: einvo-webhooks/1.0
X-Einvo-Event: document.status
X-Einvo-Delivery: 5f0c6c58-2d55-4a5e-9a8c-7e3b7d0f1a9b
X-Einvo-Signature: t=1795075200,v1=8d4f3a...e21
{
"id": "0b8d3e4c-41f1-4b6c-a1f5-2c9e7d6a5b40",
"type": "document.status",
"createdAt": "2026-11-19T08:40:00Z",
"data": {
"documentId": "7c1d1f9e-3a52-4b7e-9d1c-0f3e5b1a2c44",
"direction": "OUTBOUND",
"kind": "INVOICE",
"status": "DELIVERED",
"number": "INV-2026-00042",
"issueDate": "2026-11-19",
"sender": "0235:1987654321",
"receiver": "0235:1345678901",
"currency": "AED",
"totalAmount": 1050.00,
"taxAmount": 50.00,
"ublUrl": "/api/v1/invoices/7c1d1f9e-3a52-4b7e-9d1c-0f3e5b1a2c44/ubl",
"sandbox": false
}
}
document.fta adds data.ftaStatus and data.ftaMessage. Fetch the UBL with ublUrl and an API key with
documents:read. Use X-Einvo-Delivery to ignore duplicates: the same delivery can arrive more than once.
Responses and retries
Answer with any 2xx within 15 seconds; process the event asynchronously if it takes longer. Any other answer, a timeout or a connection
error is retried with exponential backoff (30 seconds, 1, 2, 4 minutes…), up to 10 attempts over several hours. The portal shows every delivery attempt with its HTTP status.
Verify the signature
X-Einvo-Signature: t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw body>"
with the endpoint secret. Compute it on the raw bytes before parsing JSON, compare in constant time and reject timestamps older than
5 minutes (replays). The SDKs include this helper.
Node.js
import crypto from 'node:crypto';
// rawBody: the request body exactly as received (Buffer or string), before JSON parsing
export function verifyEinvoSignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
const t = Number(parts.t);
if (!t || !parts.v1 || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const a = Buffer.from(expected, 'hex'), b = Buffer.from(parts.v1, 'hex');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Express: app.post('/einvo', express.raw({ type: 'application/json' }), (req, res) => {
// if (!verifyEinvoSignature(req.body, req.get('X-Einvo-Signature'), process.env.EINVO_WEBHOOK_SECRET)) return res.sendStatus(400);
// const event = JSON.parse(req.body); ...; res.sendStatus(204); });
Python
import hashlib, hmac, time
def verify_einvo_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.strip().split("=", 1) for p in header.split(","))
try:
t = int(parts["t"])
except (KeyError, ValueError):
return False
if abs(time.time() - t) > tolerance or "v1" not in parts:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
# Flask: verify_einvo_signature(request.get_data(), request.headers["X-Einvo-Signature"], SECRET)
Java
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HashMap;
import java.util.HexFormat;
import java.util.Map;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public static boolean verifyEinvoSignature(String rawBody, String header, String secret) throws Exception {
Map<String, String> parts = new HashMap<>();
for (String p : header.split(",")) {
String[] kv = p.trim().split("=", 2);
if (kv.length == 2) parts.put(kv[0], kv[1]);
}
long t;
try { t = Long.parseLong(parts.get("t")); } catch (RuntimeException e) { return false; }
if (Math.abs(System.currentTimeMillis() / 1000 - t) > 300 || parts.get("v1") == null) return false;
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
byte[] expected = mac.doFinal((t + "." + rawBody).getBytes(StandardCharsets.UTF_8));
return MessageDigest.isEqual(expected, HexFormat.of().parseHex(parts.get("v1")));
}
C#
using System.Security.Cryptography;
using System.Text;
public static bool VerifyEinvoSignature(string rawBody, string header, string secret, int toleranceSeconds = 300)
{
var parts = header.Split(',').Select(p => p.Trim().Split('=', 2)).Where(kv => kv.Length == 2)
.ToDictionary(kv => kv[0], kv => kv[1]);
if (!parts.TryGetValue("t", out var ts) || !long.TryParse(ts, out var t) || !parts.TryGetValue("v1", out var v1))
return false;
if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > toleranceSeconds) return false;
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
var expected = hmac.ComputeHash(Encoding.UTF8.GetBytes($"{t}.{rawBody}"));
try { return CryptographicOperations.FixedTimeEquals(expected, Convert.FromHexString(v1)); }
catch (FormatException) { return false; }
}