Feature: Callback URLs

Understanding Callback URLs

When you submit an invoice via POST /invoices to the DigiTax Tanzania API, the invoice transitions through the fiscal lifecycle:

{
  "id": "invoice_01HC3J1VVVM05YCTS61G7V3KC6",
  "status": "PENDING",
  "receipt_number": null,
  "verification_code": null,
  "verification_url": null,
  "issued_at": null
}

DigiTax queues the invoice and transmits it to TRA's EFDMS. Once EFDMS validates and signs the transaction, the status transitions to ISSUED:

{
  "id": "invoice_01HC3J1VVVM05YCTS61G7V3KC6",
  "status": "ISSUED",
  "receipt_number": 42,
  "verification_code": "ABCD1234",
  "verification_url": "https://virtual.tra.go.tz/efdmsRctVerify/Home/Index?rctvnum=ABCD1234",
  "tax_exclusive_total": 100000,
  "tax_inclusive_total": 118000,
  "issued_at": "2026-07-14T12:00:00Z"
}

EFDMS processing takes seconds depending on server load. Rather than polling repeatedly, you can configure a callback URL or webhook to be notified automatically when fiscalization completes.

Where to use Callback URLs

Configure webhook endpoints in your DigiTax Dashboard under the Integrations tab, or pass an optional callback_url property when creating an invoice:

Create an invoice (POST /invoices)

During testing, we recommend using webhook.site to inspect incoming callbacks.

Scenarios

DigiTax triggers a webhook event when EFDMS fiscalizes the invoice (invoice.issued) or when TRA rejects it (invoice.failed).

Structure and example

{
  "event": "invoice.issued",
  "data": {
    "id": "invoice_01HC3J1VVVM05YCTS61G7V3KC6",
    "invoice_number": "INV26-195-120000123-ABCDEF",
    "trader_invoice_number": "INV-2026-001",
    "status": "ISSUED",
    "receipt_number": 42,
    "verification_code": "ABCD1234",
    "verification_url": "https://virtual.tra.go.tz/efdmsRctVerify/Home/Index?rctvnum=ABCD1234",
    "tax_exclusive_total": 100000,
    "tax_inclusive_total": 118000,
    "issued_at": "2026-07-14T12:00:00Z"
  }
}