> 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/outputs.md).

# Outputs

What comes out of novu-bridge

## Overview

The dispatch log, the DLQ, and the delivery receipts the bridge accepts. Thin events are resolved into v1 envelopes in-process, so both inbound kinds produce the same outputs; a thin event yields N rows, each marked `source_path = RESOLVED`.

## Details

### The dispatch log

Table `nb_dispatch_log`: one row per terminal outcome per recipient × channel, including rejections and decisions taken before any recipient or channel existed. Read it with `GET /novu-adapter/v1/logs` (masked) or Configurator → Notifications → **Logs**.

#### Statuses

<table><thead><tr><th width="141.8125">Status</th><th width="381.8359375">Meaning</th><th>Written by</th></tr></thead><tbody><tr><td><code>REJECTED</code></td><td>Failed validation (envelope or thin event); written before the error is thrown, then DLQ'd</td><td><code>DispatchPipelineService</code> / <code>ThinEventPipelineService</code></td></tr><tr><td><code>SKIPPED</code></td><td>Well-formed; a deliberate decision not to deliver (gates, resolution decisions). Never DLQ'd</td><td>gates, resolver</td></tr><tr><td><code>RECEIVED</code></td><td>Validation only (<code>POST /dispatch/_validate</code>, or <code>_dry-run</code> without <code>send</code>)</td><td>dry-run path</td></tr><tr><td><code>SENT</code></td><td>A transport <strong>accepted</strong> it — not delivered</td><td>dispatch path</td></tr><tr><td><code>QUEUED</code></td><td><code>messages/_send</code> only: Novu took the sign-in code and the provider had not answered within <code>NOVU_BRIDGE_MESSAGES_CONFIRM_TIMEOUT_MS</code> (the API's <code>202 QUEUED</code>). Nothing updates it later</td><td><code>MessageSendService</code></td></tr><tr><td><code>DELIVERED</code></td><td>A receipt confirmed delivery; stamps <code>delivered_time</code></td><td><code>ReceiptController</code></td></tr><tr><td><code>BOUNCED</code></td><td>A receipt reported a bounce</td><td><code>ReceiptController</code></td></tr><tr><td><code>FAILED</code></td><td>Transport refused or threw, or a receipt reported failure</td><td>dispatch path, <code>ReceiptController</code></td></tr></tbody></table>

```
envelope ─► REJECTED | SKIPPED | RECEIVED | FAILED        (terminal)
         └► SENT ─► DELIVERED | BOUNCED | FAILED (NB_PROVIDER_FAILED)
```

Only `SENT` can change, and only via a receipt (`WHERE status = 'SENT'`), so late or duplicate receipts never regress a row; `QUEUED` stays as it is. `SKIPPED` never becomes `SENT`: re-enabling a channel does not resend.

#### Channel-less rows

When the resolver decides before there is a channel (no routing, no recipients, fan-out refused, unknown audience scheme) or a thin event is rejected at validation:

<table><thead><tr><th width="282.234375">Column</th><th>Value</th></tr></thead><tbody><tr><td><code>channel</code></td><td><code>NONE</code></td></tr><tr><td><code>recipient_value</code></td><td><code>none</code></td></tr><tr><td><code>transaction_id</code></td><td><code>&#x3C;transactionSeed>:NONE</code></td></tr><tr><td><code>status</code></td><td><code>SKIPPED</code>, or <code>REJECTED</code> at validation</td></tr><tr><td><code>last_error_code</code></td><td><code>NB_NO_ROUTING</code>, <code>NB_NO_RECIPIENTS</code>, <code>NB_UNKNOWN_AUDIENCE_SCHEME</code>, <code>NB_RECIPIENT_LIMIT_EXCEEDED</code>, <code>NB_INVALID_THIN_EVENT</code>, <code>NB_EVENT_NOT_IN_CATALOGUE</code></td></tr><tr><td><code>source_path</code></td><td><code>RESOLVED</code></td></tr></tbody></table>

`NB_NO_TEMPLATE` rows carry the real channel.

#### Idempotency

Unique key `(transaction_id, channel, recipient_value)`; writes are upserts, so Kafka redelivery updates the row and two recipients of one event coexist. A thin event's `transactionSeed` becomes `<seed>:<subscriberId>:<channel>` (default seed `<eventId>`); the seed is one per occurrence of the event, stable on redelivery and replay (thin-event-v1.schema.json `transactionSeed`). A `transactionId` that is already `SENT` or `DELIVERED` is not sent again: a redelivery or replay of it leaves the row as it is. The check is check-then-act, so two copies arriving at the same moment can both be sent. A random `transactionId` per attempt gives one row per attempt. A core SMS gets `CORE:<tenant>:<uuid>`, the UUID derived from the Kafka record's topic, partition, offset and timestamp: each OTP is its own row, a redelivery of the same record is the same row and is not sent again, and no phone number is in it.

#### Columns

<table><thead><tr><th width="196.421875">Column</th><th width="229.66796875">Type</th><th>Notes</th></tr></thead><tbody><tr><td><code>id</code></td><td>UUID PK</td><td></td></tr><tr><td><code>event_id</code></td><td>varchar(64) NOT NULL</td><td><code>eventId</code>; <code>unknown</code> on a rejection without one</td></tr><tr><td><code>transaction_id</code></td><td>varchar(256) NOT NULL</td><td><code>transactionId</code>, else <code>&#x3C;eventId>:&#x3C;channel></code>; unique key part</td></tr><tr><td><code>reference_number</code></td><td>varchar(256)</td><td><code>entityId</code>, else <code>data.referenceNumber</code>, else <code>data.complaintNo</code>, else <code>eventId</code>; exact or prefix filter</td></tr><tr><td><code>module</code></td><td>varchar(128) NOT NULL</td><td><code>unknown</code> on a rejection without one</td></tr><tr><td><code>event_name</code></td><td>varchar(256) NOT NULL</td><td></td></tr><tr><td><code>tenant_id</code></td><td>varchar(256) NOT NULL</td><td></td></tr><tr><td><code>channel</code></td><td>varchar(64) NOT NULL</td><td><code>UNKNOWN</code> on an envelope rejection without one; <code>NONE</code> on channel-less rows</td></tr><tr><td><code>source_path</code></td><td>varchar(32) NOT NULL, default <code>PRERENDERED</code></td><td><code>PRERENDERED</code> | <code>RESOLVED</code>; filter <code>sourcePath</code></td></tr><tr><td><code>recipient_value</code></td><td>varchar(256) NOT NULL</td><td><code>subscriberId</code> or <code>none</code>; stored raw, masked on read (a user uuid is an id and is shown as it is; a phone becomes <code>***</code> + its last 3 digits, an email <code>c***@domain</code> — the rule on <code>GET /logs</code> in openapi.yaml); unique key part</td></tr><tr><td><code>template_key</code></td><td>varchar(256)</td><td><code>templateKey</code>, else <code>&#x3C;audience>.&#x3C;action>.&#x3C;toState>.&#x3C;channel>.&#x3C;locale></code>, else <code>eventName</code></td></tr><tr><td><code>template_version</code></td><td>varchar(64)</td><td>reserved</td></tr><tr><td><code>status</code></td><td>varchar(32) NOT NULL</td><td>see above</td></tr><tr><td><code>attempt_count</code></td><td>int NOT NULL</td><td>always 1 — no internal retry</td></tr><tr><td><code>last_error_code</code> / <code>last_error_message</code></td><td>varchar(128) / text</td><td><code>NB_*</code> code; provider's own words, stored raw, phones and emails masked on read</td></tr><tr><td><code>provider_response_jsonb</code></td><td>jsonb</td><td>transport acceptance, later the receipt; deep-masked on read. <code>novuAccount: tenant:&#x3C;root></code> when the message went through a tenant's own Novu organization (tenant-accounts.md); absent = the shared account</td></tr><tr><td><code>is_test</code></td><td>boolean NOT NULL, default false</td><td>test-sends; hidden unless <code>includeTest=true</code></td></tr><tr><td><code>provider_ref</code></td><td>varchar(256)</td><td>provider correlation id (Novu transactionId, SMSCountry job id)</td></tr><tr><td><code>delivered_time</code></td><td>bigint</td><td>set by a <code>DELIVERED</code> receipt</td></tr><tr><td><code>created_time</code>, <code>last_modified_time</code></td><td>bigint NOT NULL</td><td>epoch millis</td></tr></tbody></table>

Indexes: unique `(transaction_id, channel, recipient_value)`; `(status, last_modified_time)`, `(tenant_id, event_name)`, `(reference_number)`, `(provider_ref)`, `(tenant_id, is_test)`, `(tenant_id, source_path)`.

**Test-send rows** (`POST /providers/test-send`; a test refused before sending, e.g. `409 NB_PROVIDER_UNAVAILABLE`, writes none): at the operator's tenant, `is_test = true`, `event_name` and `template_key` = `TEST`, subscriber `nb-test-<sha256(seed)[0:16]>` (the same for every test to one recipient), transaction id `nb-test_<uuid>`, new for every test (one row per test). A caller-supplied `transactionId` is used as given; Novu does not send a repeat of one. On a workspace's own organisation, the seed starts with the workspace, so each workspace has its own test subscriber.

**OTP rows** (`POST /messages/_send`): module `identity`, `event_name` = `OTP_SEND`, `template_key` = `OTP`, `recipient_value` = `otp_<uuid>`, a UUID-shaped SHA-256 of `root:recipient` (stable per tenant and number; never the phone or address), `transaction_id`, `event_id` and `provider_ref` = Novu's transaction id `otp_<uuid>`, status `SENT`, `QUEUED` (the provider had not answered yet: the API's 202) or `FAILED` (`NB_PROVIDER_FAILED`, `NB_NOVU_*`). Both ids are UUID-shaped, so the masking on read shows them as they are. The code is never stored.

### The DLQ

Topic `novu-bridge.dlq` (`NOVU_BRIDGE_KAFKA_DLQ_TOPIC`).

```json
{ "event": { "…the message as received…" },
  "sourceTopic": "notifications.events",
  "errorCode": "NB_UNSUPPORTED_EVENT_TYPE",
  "errorMessage": "eventType XYZ_THING is not one of [COMPLAINTS_WORKFLOW_TRANSITIONED, CORE_SMS]" }
```

`event` is the envelope or thin event as received, or the raw `SMSRequest` for a core-SMS translation failure. `errorCode` is `NB_PROCESSING_ERROR` when the failure carried no code.

**Core SMS is redacted.** For a core-SMS translation failure, and for any `CORE_SMS` envelope that fails, the text (`message`/`body`/`text`, `renderedBody`, `subject`, `contentVariables`) is **removed** and phone numbers, emails, `subscriberId` and `transactionId` are masked (`***678`), as are phones in `errorMessage`. A top-level `redacted` array names each field changed, e.g. `["message", "mobileNumber"]` or `["renderedBody", "subscriberId", "contact.phone"]`. The text is an OTP, a password-reset link or a temporary password; the DLQ keeps it for days, and a replay would skip the expiry check. Such a message is for diagnosis only: replayed, it is refused (`NB_INVALID_CORE_SMS` / `NB_INVALID_EVENT`) rather than sent. The user asks for a new OTP.

* **DLQ'd:** envelope and thin-event rejections, and any failure that throws (provider exception, Novu transport failure).
* **Not DLQ'd:** every `SKIPPED` outcome, and a clean non-2xx provider answer (recorded `FAILED`).

No automatic replay and no retry topic: fix the cause and reproduce `event` to an input topic; the upsert updates the existing row.

### Delivery receipts

`POST` or `GET /novu-adapter/v1/receipts/{provider}` — the only way a row leaves `SENT`.

* **Auth:** `novu.bridge.receipts.secret` as header `X-Receipt-Secret` or query `secret`. Blank = endpoint off (403). Outside `ProxyAuthFilter`.
* **Matching:** by `transaction_id` or `provider_ref`. Neither present → `matched: 0`.
* **Parsing:** query parameters and JSON body are merged (`secret` removed) and searched up to 3 levels deep:

<table><thead><tr><th width="173.87890625">Role</th><th>Keys</th></tr></thead><tbody><tr><td>transaction id</td><td><code>transactionId</code>, <code>transaction_id</code>, <code>txn</code></td></tr><tr><td>provider ref</td><td><code>providerRef</code>, <code>provider_ref</code>, <code>jobno</code>, <code>jobId</code>, <code>JobNo</code>, <code>jobid</code>, <code>messageId</code>, <code>message_id</code>, <code>sid</code>, <code>MessageSid</code></td></tr><tr><td>outcome</td><td><code>status</code>, <code>Status</code>, <code>event</code>, <code>type</code>, <code>eventType</code>, <code>deliveryStatus</code>, <code>MessageStatus</code></td></tr><tr><td>error text</td><td><code>error</code>, <code>errorMessage</code>, <code>reason</code>, <code>ErrorMessage</code>, <code>errorCode</code></td></tr></tbody></table>

Outcome words, case-insensitive substring, first match wins: `undeliv`, `fail`, `reject`, `expir`, `error` → `FAILED`; `bounce` → `BOUNCED`; `deliv`, `dlvrd` → `DELIVERED`; anything else (`queued`, `sent`, `read`, …) is acknowledged and ignored.

<table><thead><tr><th width="201.51171875">Provider path</th><th>Typical report</th></tr></thead><tbody><tr><td><code>/receipts/novu</code></td><td><code>{"type": "message.delivered", "data": {"transactionId": "…"}}</code></td></tr><tr><td><code>/receipts/smscountry</code></td><td><code>GET …/receipts/smscountry?jobno=4689&#x26;status=DELIVRD&#x26;secret=…</code> (<code>jobno</code> = the job id SMSCountry returned to the legacy direct route, stored as <code>provider_ref</code>. A message sent through an SMSCountry <em>provider</em> has Novu's <code>transactionId</code> as its <code>provider_ref</code> — the job id stays in Novu's message record — so a DR for it matches no row)</td></tr></tbody></table>

Matching does not depend on which Novu account sent the message: transaction IDs are unique, so a receipt for a message a tenant's own organisation sent is filed under the right row. Each sender's report has to be configured where it is sent from, though: a gateway DR callback or Novu webhook set up for the shared account does not cover a tenant's own providers (tenant-accounts.md).

Other path segments are parsed the same way but need a Kong route. The response is always `200` once authenticated, e.g. `{"provider": "smscountry", "providerStatus": "DELIVRD", "status": "DELIVERED", "matched": 1}`; `matched: 0` means no row matched, the outcome was non-terminal, or the row had already left `SENT`.


---

# 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/outputs.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.
