Skip to content
/
Overview

Cheqi webhooks notify your integration when an encrypted receipt, credit note, or return request is ready. Webhooks remove the need to poll and preserve Cheqi's zero-knowledge boundary: receipt and credit-note documents remain encrypted for the receiving integration.

Event contract

Every request has two top-level properties:

{
  "event": "RECEIPT_CREATED",
  "data": {
    "encryptedReceipt": {
      "cheqiReceiptId": "CHQ-20260803-ABC123",
      "encryptedEnvelope": "base64-ciphertext...",
      "encryptedEnvelopeKey": "base64-wrapped-key..."
    }
  }
}
  • event identifies the lifecycle event.
  • data contains exactly one event-specific object, such as encryptedReceipt, encryptedCreditNote, or creditNoteInitiationRequest.

See Webhook Events for every event shape.

Available events

EventObject in dataDescription
RECEIPT_CREATEDencryptedReceiptA recipient-specific encrypted receipt envelope is ready.
RETURN_REQUESTEDcreditNoteInitiationRequestA customer submitted an encrypted return request.
CREDIT_NOTE_CREATEDencryptedCreditNoteA recipient-specific encrypted credit-note envelope is ready.

Delivery sequence

  1. Register an HTTPS endpoint and select event types.
  2. Cheqi sends the event as an HTTP POST.
  3. Verify X-Cheqi-Signature against the exact raw request body.
  4. Persist or enqueue the event before doing expensive work.
  5. Return a successful 2xx response promptly.
  6. Decrypt encrypted payloads asynchronously.

Webhook delivery may be retried. Make processing idempotent using the combination of event and cheqiReceiptId from the event-specific data object.

Encrypted documents

For RECEIPT_CREATED and CREDIT_NOTE_CREATED, encryptedEnvelope is the ciphertext of a ReceiptEnvelope. After decryption, ReceiptEnvelope.documents contains the authoritative set of generated documents. Cheqi does not send separate customer-detail ciphertext or a separate receipt-format list.

Continue with:

UBL XML Format

Setup