Every document sent to ZATCA generates a webhook about the current state.
This webhook can be consumed to keep the integration and data up-to-date.


Currently only events regarding reporting are supported. These events are can be found below.

Event types

Credit Note:

  • zatca.credit_note.failed
  • zatca.credit_note.pending
  • zatca.credit_note.reported

Debit Note:

  • zatca.debit_note.failed
  • zatca.debit_note.pending
  • zatca.debit_note.reported


  • zatca.invoice.failed
  • zatca.invoice.pending
  • zatca.invoice.reported

Simplified Credit Note

  • zatca.simplified_credit_note.failed
  • zatca.simplified_credit_note.pending
  • zatca.simplified_credit_note.reported

Simplified Debit Note

  • zatca.simplified_debit_note.failed
  • zatca.simplified_debit_note.pending
  • zatca.simplified_debit_note.reported

Simplified Invoice

  • zatca.simplified_invoice.failed
  • zatca.simplified_invoice.pending
  • zatca.simplified_invoice.reported


    "payload": {
        "document": {
            "id" : <uuid4>,
            "document_number": <credit-note-number | debit-note-number | invoice-number>,
						"issue_datetime": <datetime-in-ISO-8601-UTC>,
						"supply_date" <date-ofsupply>
        "status": <failed | pending | reported>,
        "response: <null | response-returned-by-ZATCA>
    "event_id": <uuid4>,
    "event_type": <one-of-event-types>,
    "timestamp": <datetime-in-ISO-8601-UTC>


Webhooks are sent from remote party and to make sure that the webhook was sent from expected party, the special header X-Wafeq-Webhook-Secret has been added. This header is UNIQUE per integration and therefore can be used for validation. In case of leakage of this "secret" it can and should be regenerated.

Example of webhook

Content-Length: 703
Content-Type: application/json
Host: app.example.com
Accept: application/json
X-Wafeq-Webhook-Secret: 4cbf513c-d96a-4f3d-83ff-de637283d7aa

    "payload": {
        "document": {
            "id": "61d7226e-c04a-4e55-a459-ad442812dbf0",
            "document_number": "INV-2023-001",
            "issue_datetime": "2023-09-04T13:05:38.113425Z",
            "supply_date": "2023-01-01"
        "status": "reported",
        "response": {
            "detail": {
                "validationResults": {
                    "infoMessages": [
                            "type": "INFO",
                            "code": "XSD_ZATCA_VALID",
                            "category": "XSD validation",
                            "message": "Complied with UBL 2.1 standards in line with ZATCA specifications",
                            "status": "PASS"
                    "warningMessages": [],
                    "errorMessages": [],
                    "status": "PASS"
                "reportingStatus": "REPORTED"
            "status": 200
    "event_id": "68158622-72be-4e53-8a2d-5e813c959abf",
    "event_type": "zatca.simplified_invoice.reported",
    "timestamp": "2023-09-04T13:05:44.887378Z"