# Callbacks and webhooks

**Audience: integrators receiving callbacks.** This guide explains how to receive status notifications in your own application. Callback settings can be supplied through an API or a Web submission form. If you only need to track communications in the Web app, follow the [issuer tracking instructions](/products/namirialnotify/issuer/transactions-search).

Namirial Notify can send HTTP push notifications to your system whenever a transaction changes state. This allows your application to react to delivery events in real time without polling the Query endpoints.

Callbacks are configured per transaction at submission. The following fields describe the API configuration; Web forms expose the callback URL and event filter in the **Advanced** tab.

## Configuration fields

### `PushNotificationUrl`

The URL where Namirial Notify will POST a callback when a matching state change occurs. Your endpoint must be publicly accessible.

```json
"PushNotificationUrl": "https://your-system.example.com/callbacks/notify"
```

### `PushNotificationFilter`

An array of supported state or event names that should trigger a callback. For example, `Closed` reports lifecycle closure and `AffidavitPublished` reports a generated affidavit. An affidavit callback is not a new lifecycle state. Supply a callback URL and a nonempty filter together. Omit both when you do not need callbacks.

Available values depend on the service — see the per-service filter tables [below](#available-filter-values-by-service).

### `PushNotificationExtraData`

An optional free-text string included in every callback for this transaction. Use it to pass correlation data your system needs to route the notification — for example, an internal order ID or reference.

```json
"PushNotificationExtraData": "order-12345"
```

This value is returned inside `AdditionalData.ExtraData` in the callback payload.

## Callbacks and batch sending

When you send through the [batch API](/products/namirialnotify/apis/evinotice-api#batch-operations), the callback settings you configure on the batch (`PushNotificationUrl` / `BatchPushNotificationUrl`, `PushNotificationFilter`, `PushNotificationExtraData`) are **propagated to every evidence** generated from the batch. Each generated notice, email, or SMS then fires the **normal per-evidence callbacks** described on this page — there is no separate batch-level callback event.

`PushNotificationUrl` and `BatchPushNotificationUrl` on a batch are aliases for the same value. The **batch's own** lifecycle (`Draft`, `Submitted`, `Scheduled`, `Processing`, `Processed`, `Invalid`, `Failed`) is **not** pushed — track it by polling `GET /v2/Evi{Service}/Batches/{BatchId}`.

## Available filter values by service

### EviSMS

| Value | Triggered when |
|  --- | --- |
| `Ready` | Message has been locally processed and is ready to send. |
| `Dispatched` | The system has completed local processing; the message is ready to be sent to the telecommunications operator. |
| `Sent` | The telecommunications operator accepted the message for routing. |
| `Delivered` | Message was delivered to the recipient's device. |
| `Read` | Recipient opened the message (where channel supports it). |
| `Failed` | A failure state was recorded. A retry or fallback can occur without this callback. |
| `Closed` | Tracking ended. Check the final outcome. |
| `AffidavitPublished` | A new affidavit has been published for this message. |


`Replied` is accepted as a submit filter value for backward compatibility, but
the EviSMS pipeline does not emit a `Replied` callback and the current Query
contract exposes neither a `Replied` state nor a `RepliedOn` timestamp. Do not
rely on it. EviMail and EviNotice do emit `Replied`.

### EviMail

| Value | Triggered when |
|  --- | --- |
| `Ready` | Message has been locally processed and is ready to send. |
| `Dispatched` | Sending has been requested; the message is ready for the sender component. |
| `Sent` | The recipient's mail server accepted the message. |
| `Delivered` | Delivery confirmation was received. |
| `Read` | The first supported opening or read signal was recorded. |
| `Replied` | Recipient accepted or rejected the message. |
| `Failed` | A processing, transmission, or delivery failure was recorded. An SMTP attempt scheduled for retry does not trigger this callback. |
| `Closed` | Tracking complete; no further events expected. |
| `AffidavitPublished` | An affidavit has been published/generated for this message. |


### EviNotice

| Value | Triggered when |
|  --- | --- |
| `Processed` | Initial processing and content certification completed; the notification is ready for a send request. |
| `Dispatched` | The platform completed its initial checks, accepted responsibility for the communication and issued the notification send request; successful transmission has not yet been confirmed. |
| `Sent` | The selected sending channel reported successful transmission of the notification. |
| `Delivered` | A best-effort delivery signal was received for the notification; this does not establish that the hosted content was opened. |
| `Received` | Recipient followed the link and reached the hosted notice. |
| `Read` | Recipient opened and read the hosted notice content. |
| `Replied` | Recipient accepted or rejected the notice. |
| `Failed` | A processing, transmission or delivery failure occurred. It is not final by itself: wait for `Closed` and inspect `Outcome`. Initial processing failures close immediately; other failures can recover while the notice remains open. |
| `Closed` | Notice lifecycle complete; requested affidavits can still generate `AffidavitPublished` callbacks. |
| `AffidavitPublished` | An affidavit has been published/generated for this notice. |


### EviPost

Set both the callback URL and a non-empty filter, or omit both. Submit returns `400` if only one is set or a filter value is repeated.

| Value | Triggered when |
|  --- | --- |
| `Processed` | Postal communication has been locally processed. |
| `Dispatched` | Dispatched to the postal communication system. |
| `Sent` | Handed off to the postal operator or messaging service. |
| `Delivered` | Delivery with proof was recorded. |
| `Closed` | Postal tracking ended. Affidavit callbacks can still arrive afterwards. |
| `Cancelled` | A cancellation attempt was processed. Check `AdditionalData.Success`: `true` confirms cancellation; `false` reports an unsuccessful attempt. |
| `Issued` | Item issued by the postal operator. |
| `Disposed` | The provider reported destruction of the undelivered item under a service configured for disposal. |
| `AffidavitPublished` | An affidavit has been published or regenerated for this communication. |


### EviSign

| Value | Triggered when |
|  --- | --- |
| `Processed` | The signature workflow was prepared and certified. |
| `Sent` | A party’s signature or review request was attempted, sent or abandoned. Check `AdditionalData.TransmissionSuccess` and `AdditionalData.EventDescription`. |
| `Delivered` | Delivery of a party’s signature or review request was reported. |
| `Signed` | One signer completed the signing step. |
| `Rejected` | One signer rejected the document. |
| `FullySent` | Aggregate sending milestone for the signing and review parties. |
| `FullyDelivered` | Aggregate delivery milestone for the workflow. |
| `FullySigned` | All signing and review parties completed their approval or signing step. |
| `Closed` | The workflow reached its final state. |
| `AffidavitPublished` | A new affidavit has been published for this signature workflow. |


## Callback payload

When a matching state change occurs, Namirial Notify sends an HTTP **POST** to the configured `PushNotificationUrl` with a JSON body describing the event.

Callbacks are sent with a JSON content type. The callback integration model
does not define an `Authorization` header, HMAC signature header,
shared-secret header, or a stable source-IP allowlist for origin validation.

Respond with `200 OK` after your system has validated the payload and safely
stored or queued the event for processing.

### Common fields

The shared callback envelope uses these fields, regardless of service. Nullable
values may be sent as `null` or omitted, depending on the service and event.

| Field | Type | Description |
|  --- | --- | --- |
| `Identifier` | string | Event identifier. In EviMail, different callback kinds can share it. |
| `Kind` | string | Callback or event kind (for example, `Sent`, `Delivered`, or `AffidavitPublished`). |
| `Date` | datetime | Timestamp of the event in ISO 8601 format. |
| `EvidenceId` | string | Identifier of the transaction (same as `eviId` or `Id` from Submit). |
| `EvidenceType` | string | Type of transaction — `eviMail`, `eviNotice`, `eviSMS`, `eviSign`, or `eviPost`. |
| `EvidenceState` | string/null | Populated by EviSign. For EviMail, EviNotice, EviSMS, and EviPost, accept an absent or null value and use `AdditionalData.State`. |
| `Site` | string | Name of the issuer's site. |
| `Owner` | string/null | Populated by EviSign. Not populated by EviMail, EviNotice, EviSMS, or EviPost; accept an absent or null value for those services. |
| `OwnerEmail` | string | Email of the issuer account. |
| `AdditionalData` | object | Service- and event-specific fields (see below). |


### Delivery order and reconciliation

Callbacks for different events are delivered independently. Do not assume they
arrive in lifecycle order: a callback that is being retried can arrive after a
later event for the same transaction.

- Deduplicate callbacks by `EvidenceType`, `EvidenceId`, `Kind`, and `Identifier`. A retried callback keeps the same values.
- Use `Date` as the time of the event, not as a delivery sequence number.
- If two events have the same timestamp, the callback contract does not provide
a deterministic order between them.
- Use the Query or Get endpoint to reconcile the current state, outcome, and
timestamp fields. These API responses are the authoritative snapshot.


### `AdditionalData` — common fields

These field families cover the mail, SMS, hosted-notice, and postal services. **EviSign uses a different service-specific payload shape** with signer, party, and workflow fields; for that contract, see the [EviSign service guide](/products/namirialnotify/services/evisign#callbacks-and-what-you-receive).

These fields appear inside `AdditionalData` for **EviMail** and **EviNotice**:

| Field | Description |
|  --- | --- |
| `From` | Issuer's email address. |
| `To` | Recipient address: email address, or mobile number for EviNotice. |
| `Subject` | Subject of the transaction. |
| `LookupKey` | The lookup key set by the issuer at submission. |
| `State` | Current state of the transaction. |
| `CreationDate` | Timestamp when the transaction was created. |
| `ExtraData` | The value of `PushNotificationExtraData` set at submission, if any. |


For **EviSMS**, the `AdditionalData` object uses different field names for sender and recipient:

| Field | Description |
|  --- | --- |
| `Source` | Name of the issuer. |
| `Destination` | Name or number of the recipient. |
| `LookupKey` | The lookup key set by the issuer at submission. |
| `State` | Current state of the transaction. |
| `CreationDate` | Timestamp when the transaction was created. |
| `ExtraData` | The value of `PushNotificationExtraData` set at submission, if any. |


For **EviPost**, the `AdditionalData` object also uses different field names:

| Field | Description |
|  --- | --- |
| `Sender` | Issuer legal name followed by the display name, when supplied. |
| `Recipient` | Recipient legal name, when supplied, followed by the display name. |
| `LookupKey` | The lookup key set by the issuer at submission. |
| `State` | Current state of the transaction. |
| `CreationDate` | Timestamp when the transaction was created. |
| `ExtraData` | The value of `PushNotificationExtraData` set at submission, if any. |


### `AdditionalData` — event-specific fields

Depending on the event type, additional fields are included.

**EviNotice, EviMail, EviSMS:**

| Event | Extra fields |
|  --- | --- |
| `Sent` | `XmissionDetails` — technical detail of the delivery attempt. For EviNotice and EviMail, included only for HTTPS callback URLs. |
| `Dispatched`, `Delivered`, `Read`, `Received` | `Progress` — title of the progress step; `Description` — detailed description. For `Received` and `Read` events on EviNotice, also includes `IpAddress`, `BrowserData`, `UserLanguages`, `UserIdentity`, and `UserAgent` (when available). |
| `Failed` | `Progress` — short error summary; `Description` — detailed description of the failure or retry exhaustion. For EviNotice and EviMail, these are fixed texts. Use Get or Query and the transaction history to investigate the recorded failure. |
| `Replied` (EviMail and EviNotice only) | `Kind` — `Accepted` or `Rejected`. `Comments` — recipient comments (HTTPS only for EviNotice and EviMail). EviNotice also includes `IpAddress`, `BrowserData`, `UserLanguages`, `UserIdentity` and `UserAgent` when available. |
| `Closed` | `Outcome` — final outcome of the transaction; `OutcomeDescription` — human-readable outcome description. |


**EviPost:**

| Event | Extra fields |
|  --- | --- |
| `Dispatched`, `Sent`, `Issued` | `TransmissionDetails` — technical detail of the notification or sending. |
| `Delivered` | `Details` — delivery details. |
| `Cancelled` | `Success` — `true` when the cancellation was confirmed; `false` when the attempt was unsuccessful. |
| `Closed` | `Outcome` — human-readable text for the final outcome. Its language can vary. Use the Query `outcome` field for the outcome code. `CourierCode` — included when available. |
| `Disposed` | `CourierCode` — included when available. |
| `AffidavitPublished` | `AffidavitId` and `AffidavitName` — ID and description of the affidavit. `Regenerated: true` marks regeneration. |


## Example payloads

### EviMail — `Sent` event

```json
{
  "Identifier": "1234",
  "EvidenceId": "2aca3ea149f943879726a87000c1f704",
  "EvidenceType": "eviMail",
  "Kind": "Sent",
  "Date": "2018-01-22T12:46:32.4830752+01:00",
  "Site": "my-site",
  "Owner": null,
  "OwnerEmail": "sender@example.com",
  "AdditionalData": {
    "From": "sender@example.com",
    "To": "recipient@example.com",
    "Subject": "Your certified document",
    "LookupKey": "order-12345",
    "State": "Sent",
    "CreationDate": "2018-01-22T12:46:12.3113880+01:00",
    "XmissionDetails": "Successfully sent to recipient's mail server.",
    "ExtraData": "{\"orderId\": \"99cf386b-1590-4ddb-af68-607b3e7c1194\"}"
  }
}
```

**HTTPS-only callback fields for EviMail and EviNotice.** The `XmissionDetails` field on `Sent` events and the `Comments` field on `Replied` events are only included when `PushNotificationUrl` uses HTTPS. Plain HTTP callback URLs receive the rest of the payload without these fields.

### EviNotice — `Received` event

Illustrative callback; the example progress and description text are not exact platform literals.

```json
{
  "Identifier": "0188d313-e2a9-4293-b995-c36324c889a7",
  "Kind": "Received",
  "Date": "2023-06-19T09:54:35.7608150Z",
  "EvidenceId": "0188d313642147089ab0c1398514df49",
  "EvidenceType": "eviNotice",
  "Site": "my-site",
  "OwnerEmail": "sender@example.com",
  "AdditionalData": {
    "From": "sender@example.com",
    "To": "recipient@example.com",
    "Subject": "Your certified notice",
    "State": "Received",
    "CreationDate": "2023-06-19T09:54:03.7486430Z",
    "Progress": "Received of the notification confirmed",
    "Description": "The recipient followed the notice link and reached the hosted content.",
    "IpAddress": "188.26.211.105",
    "BrowserData": "Chrome",
    "UserLanguages": "es-ES, es;q=0.9"
  }
}
```

### EviPost — `AffidavitPublished` event (including on-demand affidavits)

Affidavit-related callbacks for EviPost — including those generated by `POST /v1/EviPost/AffidavitRequest` — use the **same envelope** as state-change callbacks, with `Kind` set to `AffidavitPublished`. They are posted to the `PushNotificationUrl` originally configured on the EviPost submission, provided `AffidavitPublished` was included in `PushNotificationFilter`.

The `AdditionalData` for EviPost uses `Sender` and `Recipient` instead of `From` and `To` (which are the EviMail/EviNotice field names).

```json
{
  "Identifier": "000c1f70-42ac-a3ea-149f-943879726a87",
  "Kind": "AffidavitPublished",
  "Date": "2026-01-22T11:46:32.4830752Z",
  "EvidenceId": "87ffa214e7734bd59b8da8ef00fd80f8",
  "EvidenceType": "eviPost",
  "Site": "my-site",
  "Owner": null,
  "OwnerEmail": "sender@example.com",
  "AdditionalData": {
    "Sender": "Sender Name",
    "Recipient": "Recipient Name",
    "LookupKey": "order-12345",
    "State": "Sent",
    "CreationDate": "2026-01-22T12:46:12.3113880+01:00",
    "AffidavitId": "000c1f70-42ac-a3ea-149f-943879726a87",
    "AffidavitName": "Certification of postal communication (upon request)"
  }
}
```

EviPost does not populate the affidavit kind or the on-demand request ID in these callbacks. Use `AdditionalData.AffidavitId` to locate or download the affidavit. Compare IDs as UUIDs: the callback uses dashes and Query omits them. See [EviPost callback reliability](/products/namirialnotify/services/evipost#callback-reliability) for regeneration.

### EviMail — `AffidavitPublished` event (including on-demand affidavits)

Affidavit-related callbacks for EviMail — including those generated by `POST /v1/EviMail/AffidavitRequest` — use the same envelope as state-change callbacks, with `Kind` set to `AffidavitPublished`. They are posted to the `PushNotificationUrl` originally configured on the EviMail submission, provided `AffidavitPublished` was included in `PushNotificationFilter`.

`AffidavitPublished` can be emitted for any generated or published affidavit. `AffidavitRequest` does not accept a separate callback URL; on-demand request results are delivered on the EviMail's existing push URL and include `RequestId` when applicable.

```json
{
  "Identifier": "1234",
  "Kind": "AffidavitPublished",
  "Date": "2026-01-22T12:46:32.4830752+01:00",
  "EvidenceId": "2aca3ea149f943879726a87000c1f704",
  "EvidenceType": "eviMail",
  "Site": "my-site",
  "Owner": null,
  "OwnerEmail": "sender@example.com",
  "AdditionalData": {
    "From": "sender@example.com",
    "To": "recipient@example.com",
    "Subject": "Your certified document",
    "LookupKey": "order-12345",
    "State": "Read",
    "CreationDate": "2026-01-22T12:46:12.3113880+01:00",
    "AffidavitId": "000c1f7042aca3ea149f943879726a87",
    "AffidavitKind": "OnDemand",
    "AffidavitName": "Certification of certified e-mail (on request)",
    "RequestId": "79726a87000c1f7042aca3ea149f9438"
  }
}
```

`RequestId` is only present when the affidavit was produced by an on-demand request. A `Regenerated: true` entry is added when the affidavit was regenerated by the platform rather than published for the first time.

`AffidavitPublished` callbacks contain affidavit metadata and an identifier, not
the PDF bytes. For EviMail, EviSMS, and EviPost, pass
`AdditionalData.AffidavitId` to the shared
[`/AffidavitsDownload`](/products/namirialnotify/apis/downloads-api#download-affidavit-pdfs-by-id)
endpoint to retrieve the signed PDF in a ZIP archive.

## Handling callbacks reliably

### Process duplicate callbacks only once

The platform can send a callback again if an earlier delivery fails or times out. A timeout can happen even after your application has stored the callback. Retries of that callback retain the same `Identifier`.

Store `EvidenceType`, `EvidenceId`, `Kind`, and `Identifier` with each received event. Make this duplicate check safe for concurrent requests. Two deliveries of the same `Closed` callback should create only one follow-up task. An EviMail that fails before initial processing completes can emit `Failed` and `Closed` with the same `Identifier`, so include `Kind` to process both. EviSign can also reuse one identifier for `Sent` and `FullySent`, `Delivered` and `FullyDelivered`, or `Signed` and `FullySigned`. For EviPost, a regenerated affidavit can reuse the same key; see [EviPost callback reliability](/products/namirialnotify/services/evipost#callback-reliability).

Do not deduplicate using `EvidenceId` alone: one communication produces multiple distinct events. A duplicate already accepted by your system should still receive a successful acknowledgement.

### Acknowledge receipt promptly

Validate the payload and store or queue it durably, then return an HTTP success status such as `200 OK` (a `2xx` response). Run slower business processing afterwards. The acknowledgement confirms receipt by your application, not successful delivery of the original communication.

Errors and timeouts can trigger retries. If your application cannot safely accept the callback, do not acknowledge it as successful. For the configured retry schedule and its limits, see [Retry policy](#retry-policy).

### Match callbacks to your own records

Set `PushNotificationExtraData` to a reference such as `order-12345` when submitting the communication. The callback returns that string as `AdditionalData.ExtraData`, so your application can find the corresponding order without querying the API just to discover the reference.

This is **correlation**, not duplicate detection or authentication. Use the callback deduplication key above to detect repeats and `EvidenceId` to identify the Namirial Notify communication. Confirm the current state through Query when reconciling missed or out-of-order callbacks, or before taking an irreversible action.

## Retry policy

If your endpoint is unreachable or returns an error, Namirial Notify retries the callback. The retry count and per-attempt delay are platform configuration, not a fixed contract. The schedule below reflects the current production configuration; confirm the active values with your Namirial Notify contact before designing alerting or SLAs around them.

| Attempt | Delay after previous |
|  --- | --- |
| 1 | 30 seconds |
| 2 | 30 seconds |
| 3 | 5 minutes |
| 4 | 15 minutes |
| 5 | 30 minutes |
| 6 | 1 hour |
| 7 | 5 hours |
| 8 | 15 hours |
| 9 | 30 hours |


After the configured retries are exhausted, the callback is dropped.

Make your callback endpoint idempotent. A network timeout on your side may cause Namirial Notify to retry even if your system already processed the event. Retries are independent for each event, so they can also change the order in which callbacks arrive.

## Securing your callback endpoint

Namirial Notify does not sign callback payloads with an HMAC or include a shared-secret header. The following compensating controls are practical and recommended.

**Use HTTPS.** Configure `PushNotificationUrl` with an HTTPS endpoint. Plain HTTP exposes the payload in transit and suppresses sensitive fields (`XmissionDetails` on EviMail and EviNotice `Sent` callbacks, `Comments` on EviMail and EviNotice `Replied` callbacks).

For acknowledgement, duplicate detection, and correlation, follow [Handling callbacks reliably](#handling-callbacks-reliably).

**Treat callbacks as notifications, not the source of truth.** A callback tells you something happened. Before taking any irreversible action (sending a legal notice, releasing funds, updating a public record), verify the event by calling the Query endpoint and confirming the state and outcome match what the callback described.

**Do not order callbacks by arrival time.** Different events are delivered and retried independently. Use each callback's `Date` as the event time and reconcile with Query or Get when callbacks arrive out of order or share the same timestamp.

**Check correlation values against your records.** `EvidenceId` and `AdditionalData.ExtraData` help associate a callback with a communication you submitted. Matching values are a consistency check, not proof that the request came from Namirial Notify.

**Do not rely on source IP allowlisting unless Namirial provides official egress IP ranges for your environment.** Validate callbacks by correlation data and, before irreversible actions, by confirming the current state through the Query API rather than by source IP alone.

If your callback endpoint is temporarily unavailable, callbacks will retry on the schedule in the [Retry policy](#retry-policy) section above. After all retries are exhausted, the callback is dropped permanently. Use the Query endpoint to catch up on missed events.

## Related

- [API reference overview](/products/namirialnotify/apis/overview)
- [Integration workflows](/products/namirialnotify/dev/integration-patterns)
- [Security and authentication](/products/namirialnotify/dev/security-best-practices)
- [Performance and scaling](/products/namirialnotify/dev/performance-guidelines)
- [EviSMS API](/products/namirialnotify/apis/evisms-api)
- [EviMail API](/products/namirialnotify/apis/evimail-api)
- [EviNotice API](/products/namirialnotify/apis/evinotice-api)
- [EviPost API](/products/namirialnotify/apis/evipost-api)
- [States and outcomes](/products/namirialnotify/user-guides/states-outcomes)