28 events by subscription and zero assumptions

You configure the URL from the app, choose the events and optionally add custom headers to authenticate your receiver. The payload shape is standard and the event list is seeded from the initial migration.

Summary

When an event occurs within the workspace, factura.com.do sends a POST with a JSON body to the URL you registered. Delivery is fire-and-forget: your receiver responds 2xx and the delivery is persisted in the webhook execution log. If it responds differently, there is no automatic retry.

Subscription model

The subscription is managed from the Webhooks section of the workspace, not through a public API. You configure the destination URL, HTTP method (GET/POST/PUT), custom headers (name-value) and event selection. The app exposes an internal test endpoint to verify connectivity before activating.

Payload shape

All events share the same body shape: Event, the event name; Timestamp, ISO 8601 in the server's local time (with its offset, not normalized to UTC); and event-specific data. Keys arrive in PascalCase.

{
  "Event": "dgii.aprobado",
  "Timestamp": "2026-05-08T10:33:21.4830000-04:00",
  "data": {
    "DocumentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "StatusId": 5
  }
}

Catalog of 28 events

The 28 events cover quotations, invoices, notes, expenses, DGII statuses and catalog. All are seeded from the initial migration; subscribe only to the ones your integration needs.

The data shape per event

The envelope (<code>Event</code>, <code>Timestamp</code>, <code>data</code>) is invariant. What changes is the content of <code>data</code>. These are the fields the dispatcher emits; ignore the ones you do not use, since new fields may appear.

Each Lines item carries LineId, ProductId, ProductVariantId, WarehouseId, Code, Order, Description, IsService, IsExempt, Quantity, UnitId, UnitPrice, Discount, DiscountPercentage, Recharge, NetAmount, TotalDiscount, TotalTax, TotalWithholdings, Subtotal, Taxes and Withholdings. Accounting is the header accounting breakdown: DocumentTypeId, BranchId, SequenceTypeId, IssuedAt, LimitDate, PaymentTermId, CurrencyCode, CurrencyRate, TaxableAmount, ExemptAmount, TotalDiscount, DiscountPercentage, TotalTaxes, TotalWithholdings, Total, AmountDue, Freight, Tip, TratamientoItbis, TipoBienServicioComprado and AwaitsFiscalValidation.

Example receiver

A minimal receiver validates the secret header, reads the event and routes it. Return 2xx as soon as you persist or enqueue the work; if your logic fails, persist in the background and reconcile later.

// webhook-handler.ts (Express)
import type { Request, Response } from "express";

const SECRETO = process.env.FACTURA_WEBHOOK_SECRET!;

export function manejarWebhook(req: Request, res: Response) {
  if (req.header("X-Webhook-Secret") !== SECRETO) {
    return res.status(401).end();
  }

  const { Event, Timestamp, data } = req.body;

  switch (Event) {
    case "dgii.aprobado":
      return procesar(res, data, "aprobado");
    case "dgii.rechazado":
      return procesar(res, data, "rechazado");
    case "dgii.en_proceso":
      return procesar(res, data, "en_proceso");
    case "dgii.aceptado_condicional":
      return procesar(res, data, "aceptado_condicional");
    default:
      return res.status(204).end();
  }
}

function procesar(res: Response, data: unknown, estado: string) {
  return res.status(200).json({ estado });
}

# webhook_handler.py (FastAPI)
import os
from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()
SECRETO = os.environ["FACTURA_WEBHOOK_SECRET"]

@app.post("/webhooks/factura")
async def recibir(req: Request, x_webhook_secret: str = Header(default="")):
    if x_webhook_secret != SECRETO:
        raise HTTPException(status_code=401)

    body = await req.json()
    event = body["Event"]

    if event == "dgii.aprobado":
        # persiste en tu ERP
        return {"estado": "aprobado"}
    if event == "dgii.rechazado":
        return {"estado": "rechazado"}
    return {}

Reconciliation and plugin events

Because delivery is not retried, a lost event never arrives again. These routes let you recover what was missed by sweeping a date range: accounting-sync returns the same accounting projection as the webhook and treasury-sync, the receivables and payables (what is owed and by whom). They accept the X-Api-Key. plugins/events is different: only installed plugins use it, with their own token, to publish events to other plugins.

Next steps