Webhooks

Get notified when an e-CF changes state.

Configuration

Set webhook_url in Settings → Webhooks.
(Recommended) set webhook_secret for HMAC-SHA256 signing.
When an e-CF state changes, a signed POST is sent.
Respond 2xx to acknowledge. Otherwise the delivery is retried up to 5 times with exponential backoff (1m, 5m, 30m, 2h, 12h).

Payload

{
  "event": "ecf.status_update",
  "internalTrackId": "uuid",
  "encf": "E310000000001",
  "estado": "aceptado",
  "dgiiCode": "0",
  "dgiiMessage": "Aceptado",
  "trackId": "dgii-track-id",
  "timestamp": "2026-04-24T12:00:00.000Z"
}

Headers

Header	Description
`X-ECF-Tenant-Id`	Your tenant ID
`X-ECF-Event`	Event type (`ecf.status_update`, `webhook.test`)
`X-ECF-Delivery-Id`	Unique delivery attempt ID. use for idempotency on your side
`X-ECF-Signature`	`sha256=<hex>` HMAC-SHA256 of raw body with your secret

Verify signature (Node.js)

const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) return res.status(401).end();

Test endpoint

curl -X POST https://ecf.frandeone.com/api/webhooks/test \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" -d '{}'

Delivery history

curl "https://ecf.frandeone.com/api/webhooks/deliveries?status=failed" \
  -H "Authorization: Bearer $JWT"