> For the complete documentation index, see [llms.txt](https://docs.digit.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digit.org/complaints-management/deploy/configure/notifications/notification-contract.md).

# Notification Contract

## Overview

The published interface of novu-bridge.

<table><thead><tr><th width="235.1640625">File</th><th>Defines</th></tr></thead><tbody><tr><td><code>thin-event-v1.schema.json</code></td><td>JSON Schema (2020-12) of the inbound <strong>thin event</strong>: what happened; the bridge decides who is told and what it says</td></tr><tr><td><code>envelope-v1.schema.json</code></td><td>JSON Schema (2020-12) of the inbound <strong>envelope</strong>: a finished message for one recipient on one channel</td></tr><tr><td><code>examples/thin/</code></td><td>Thin events: PGR <code>APPLY</code>, PGR <code>ASSIGN</code>, a module with no notification code, an account-less recipient</td></tr><tr><td><code>examples/</code></td><td>Envelopes: complaint SMS, complaint email, WhatsApp with a provider template, DIGIT-core login OTP, a non-PGR module</td></tr><tr><td><code>openapi.yaml</code></td><td>OpenAPI 3.0 for every <code>/novu-adapter/v1</code> endpoint, with its auth tier, including the internal tenant-account API and <code>POST /messages/_send</code> (../tenant-accounts.md)</td></tr><tr><td><code>error-codes.md</code></td><td>Every <code>NB_*</code> code</td></tr><tr><td><code>outputs.md</code></td><td>The dispatch log, the DLQ message, delivery receipts</td></tr></tbody></table>

### One discriminator

Both kinds travel on the same input topics (../kafka-events.md). Only `kind`, read from the raw message, decides the path:

| `kind`                 | Kind       | Path                                             |
| ---------------------- | ---------- | ------------------------------------------------ |
| absent or `"RENDERED"` | envelope   | validate → gate → deliver → one dispatch-log row |
| `"THIN"`               | thin event | validate → resolve → N envelopes → N rows        |

### From a running deployment

The same documents are packaged in the jar and served unauthenticated:

```
GET /novu-bridge/novu-adapter/v1/contract/envelope      # application/json
GET /novu-bridge/novu-adapter/v1/contract/thin-event    # application/json
GET /novu-bridge/novu-adapter/v1/contract/openapi       # application/yaml
```

### Versioning

`schemaVersion` (absent = `"1"`) versions each kind independently; anything else is rejected `NB_UNSUPPORTED_SCHEMA_VERSION`. Adding an optional field is not a version change; renaming, removing or changing the meaning of a field is, and needs a v2 schema that the bridge accepts alongside v1. Java type names may change; JSON field names may not.

### Keeping it in step

Nothing checks these automatically:

* `backend/novu-bridge/src/main/resources/contract/` (served by the bridge) and this folder must stay byte-identical; edit both in the same change.
* A field added to `NotificationEvent` or `ThinEvent` goes into its schema; each schema's `required` set is what `EnvelopeValidator` / `ThinEventValidator` enforce.
* A new `NB_*` code goes into `error-codes.md` and `error-codes.txt` in the change that first emits it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.digit.org/complaints-management/deploy/configure/notifications/notification-contract.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
