# Webhooks

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:

```json
{
  "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](/webhooks/events) for every event shape.

## Available events

| Event | Object in `data` | Description |
|  --- | --- | --- |
| `RECEIPT_CREATED` | `encryptedReceipt` | A recipient-specific encrypted receipt envelope is ready. |
| `RETURN_REQUESTED` | `creditNoteInitiationRequest` | A customer submitted an encrypted return request. |
| `CREDIT_NOTE_CREATED` | `encryptedCreditNote` | A 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:

- [Webhook Setup](/webhooks/setup)
- [Webhook Events](/webhooks/events)
- [Receipt Webhooks](/webhooks/receipt-webhooks)
- [Return Webhooks](/webhooks/return-webhooks)
- [Webhook Security](/webhooks/security)