{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhooks","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":"webhooks","__idx":0},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-contract","__idx":1},"children":["Event contract"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every request has two top-level properties:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"RECEIPT_CREATED\",\n  \"data\": {\n    \"encryptedReceipt\": {\n      \"cheqiReceiptId\": \"CHQ-20260803-ABC123\",\n      \"encryptedEnvelope\": \"base64-ciphertext...\",\n      \"encryptedEnvelopeKey\": \"base64-wrapped-key...\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}," identifies the lifecycle event."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," contains exactly one event-specific object, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedReceipt"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedCreditNote"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["creditNoteInitiationRequest"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks/events"},"children":["Webhook Events"]}," for every event shape."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"available-events","__idx":2},"children":["Available events"]},{"$$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":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Object in data"},"children":["Object in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$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":["RECEIPT_CREATED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedReceipt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A recipient-specific encrypted receipt envelope is ready."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURN_REQUESTED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["creditNoteInitiationRequest"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A customer submitted an encrypted return request."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_NOTE_CREATED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedCreditNote"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A recipient-specific encrypted credit-note envelope is ready."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"delivery-sequence","__idx":3},"children":["Delivery sequence"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Register an HTTPS endpoint and select event types."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cheqi sends the event as an HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Cheqi-Signature"]}," against the exact raw request body."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Persist or enqueue the event before doing expensive work."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Return a successful ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," response promptly."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decrypt encrypted payloads asynchronously."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook delivery may be retried. Make processing idempotent using the combination of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cheqiReceiptId"]}," from the event-specific data object."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"encrypted-documents","__idx":4},"children":["Encrypted documents"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RECEIPT_CREATED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_NOTE_CREATED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedEnvelope"]}," is the ciphertext of a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope"]},". After decryption, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope.documents"]}," contains the authoritative set of generated documents. Cheqi does not send separate customer-detail ciphertext or a separate receipt-format list."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Continue with:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks/setup"},"children":["Webhook Setup"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks/events"},"children":["Webhook Events"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks/receipt-webhooks"},"children":["Receipt Webhooks"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks/return-webhooks"},"children":["Return Webhooks"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks/security"},"children":["Webhook Security"]}]}]}]},"headings":[{"value":"Webhooks","id":"webhooks","depth":1},{"value":"Event contract","id":"event-contract","depth":2},{"value":"Available events","id":"available-events","depth":2},{"value":"Delivery sequence","id":"delivery-sequence","depth":2},{"value":"Encrypted documents","id":"encrypted-documents","depth":2}],"frontmatter":{"seo":{"title":"Webhooks"}},"lastModified":"2026-08-03T14:23:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/webhooks/overview","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}