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.

Events

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

Invoice

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

{
    "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>
}

Security

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

POST HTTP/1.1
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"
}