{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Webhook Events","description":"Complete documentation for integrating Cheqi's digital receipt platform","keywords":["cheqi","digital receipts","api","sdk","java","javascript"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook-events","__idx":0},"children":["Webhook Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every Cheqi webhook has an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," property. The key inside ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," identifies the object delivered by that event."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-structure","__idx":1},"children":["Common structure"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"EVENT_NAME\",\n  \"data\": {\n    \"eventSpecificObject\": {}\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The event-specific object may contain this routing metadata:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Public OAuth client ID for the webhook subscription, when owned by a client application."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["companyId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer-company context, when applicable."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer-user context, when applicable."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Time Cheqi created the webhook event."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cheqiReceiptId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cheqi identifier of the receipt or credit note."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Null and empty fields are omitted. Do not assume both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["companyId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," are present."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"receipt_created","__idx":2},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RECEIPT_CREATED"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.encryptedReceipt"]}," contains the encrypted document envelope produced by the elected owner device for your integration."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"RECEIPT_CREATED\",\n  \"data\": {\n    \"encryptedReceipt\": {\n      \"clientId\": \"your-public-client-id\",\n      \"companyId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"created_at\": \"2026-08-03T13:30:00Z\",\n      \"cheqiReceiptId\": \"CHQ-20260803-ABC123\",\n      \"encryptedEnvelope\": \"base64-ciphertext...\",\n      \"encryptedEnvelopeKey\": \"base64-wrapped-aes-key...\",\n      \"publicKey\": \"base64-recipient-public-key-snapshot...\",\n      \"recipientKeyAlgorithm\": \"RSA_2048\",\n      \"envelopeVersion\": 1,\n      \"receiptGeneratorVersion\": \"0.3.0\",\n      \"finalHash\": \"sha256-cheqi-document-hash...\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["publicKey"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientKeyAlgorithm"]}," to select the corresponding private key and unwrap ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedEnvelopeKey"]},". Decrypt ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedEnvelope"]},", then deserialize its UTF-8 plaintext as a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#receiptenvelope"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope"]}]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["finalHash"]}," is the definitive CHEQI document hash submitted by the elected device together with the encrypted deliveries. There is no separate receipt-finalization webhook."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"return_requested","__idx":3},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURN_REQUESTED"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The customer's device encrypts a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CreditNoteInitiationRequest"]}," for the original issuer. Cheqi routes that ciphertext without decrypting it."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"RETURN_REQUESTED\",\n  \"data\": {\n    \"creditNoteInitiationRequest\": {\n      \"clientId\": \"issuer-public-client-id\",\n      \"companyId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"userId\": \"8ccf09a7-d969-4a09-880f-42d520a0999a\",\n      \"created_at\": \"2026-08-03T14:00:00Z\",\n      \"cheqiReceiptId\": \"CHQ-20260803-ABC123\",\n      \"publicKey\": \"base64-issuer-public-key...\",\n      \"encryptedCreditNoteInitiationRequest\": \"base64-ciphertext...\",\n      \"encryptedSymmetricKey\": \"base64-wrapped-aes-key...\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After decryption, the plaintext is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CreditNoteInitiationRequest"]}," containing the original receipt identifiers, requested return line items, the customer's note, and refund preference. It is not a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"credit_note_created","__idx":4},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_NOTE_CREATED"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Credit notes use the same encrypted document-bundle contract as receipts. The event-specific key is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedCreditNote"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"CREDIT_NOTE_CREATED\",\n  \"data\": {\n    \"encryptedCreditNote\": {\n      \"clientId\": \"your-public-client-id\",\n      \"companyId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"created_at\": \"2026-08-03T15:00:00Z\",\n      \"cheqiReceiptId\": \"CHQ-CN-20260803-DEF456\",\n      \"encryptedEnvelope\": \"base64-ciphertext...\",\n      \"encryptedEnvelopeKey\": \"base64-wrapped-aes-key...\",\n      \"publicKey\": \"base64-recipient-public-key-snapshot...\",\n      \"recipientKeyAlgorithm\": \"RSA_2048\",\n      \"envelopeVersion\": 1,\n      \"receiptGeneratorVersion\": \"0.3.0\",\n      \"finalHash\": \"sha256-cheqi-credit-note-hash...\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Decrypt ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedEnvelope"]}," as a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope"]},". Its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documents"]}," map contains ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI"]}," and, when requested by the recipient, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UBL_CREDIT_NOTE"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["finalHash"]}," is the definitive CHEQI credit-note hash submitted by the elected device together with the encrypted deliveries. There is no separate credit-note finalization webhook."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"receiptenvelope","__idx":5},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The plaintext obtained by decrypting a receipt or credit-note ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedEnvelope"]}," has this versioned structure:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"envelopeVersion\": 1,\n  \"receiptUuid\": \"6f9619ff-8b86-d011-b42d-00cf4fc964ff\",\n  \"cheqiReceiptId\": \"CHQ-20260803-ABC123\",\n  \"receiptGeneratorVersion\": \"0.3.0\",\n  \"documents\": {\n    \"CHEQI\": {\n      \"mediaType\": \"application/json\",\n      \"content\": \"{...}\"\n    },\n    \"UBL_INVOICE\": {\n      \"mediaType\": \"application/xml\",\n      \"content\": \"<Invoice>...</Invoice>\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Property"},"children":["Property"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["envelopeVersion"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Version of the encrypted plaintext-envelope contract."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiptUuid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shared UUID for the locally generated document bundle."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cheqiReceiptId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cheqi receipt or credit-note identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiptGeneratorVersion"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rust receipt-engine version used to generate the documents."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documents"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Map keyed by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UBL_INVOICE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UBL_PURCHASE_RECEIPT"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UBL_CREDIT_NOTE"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each document has a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mediaType"]}," and string ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]},". The keys actually present in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documents"]}," are authoritative; there is no separate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiptFormats"]}," property in the webhook."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The envelope already contains the complete generated documents, including their supplier, customer, and payment context. There is no separate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedCustomerDetails"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedCustomerAesKey"]}," payload."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"processing-steps","__idx":6},"children":["Processing steps"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the webhook signature against the raw HTTP body."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Persist the event or establish idempotency before returning success."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Select the private key corresponding to the supplied public-key snapshot."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Unwrap the AES key from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedEnvelopeKey"]}," according to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientKeyAlgorithm"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decrypt ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedEnvelope"]}," using the envelope encryption implementation in the Cheqi SDK."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deserialize the plaintext as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read the required representation from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope.documents"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Canonicalize and hash the CHEQI document when independently verifying ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["finalHash"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Do not log plaintext"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Receipt and return contents can contain personal and financial data. Do not log ciphertext keys, decrypted envelopes, or document contents."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotency-and-retries","__idx":7},"children":["Idempotency and retries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cheqi can retry a webhook when delivery fails. Process events idempotently. A practical idempotency key is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event + cheqiReceiptId"]},"; if your application can receive the same receipt for multiple authorization contexts, include the applicable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["companyId"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]}," as well."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," only after the raw event has been durably accepted. Perform decryption and downstream synchronization asynchronously."]}]},"headings":[{"value":"Webhook Events","id":"webhook-events","depth":1},{"value":"Common structure","id":"common-structure","depth":2},{"value":"RECEIPT_CREATED","id":"receipt_created","depth":2},{"value":"RETURN_REQUESTED","id":"return_requested","depth":2},{"value":"CREDIT_NOTE_CREATED","id":"credit_note_created","depth":2},{"value":"ReceiptEnvelope","id":"receiptenvelope","depth":2},{"value":"Processing steps","id":"processing-steps","depth":3},{"value":"Idempotency and retries","id":"idempotency-and-retries","depth":2}],"frontmatter":{"seo":{"title":"Webhook Events"}},"lastModified":"2026-08-03T14:23:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/webhooks/events","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}