Callbacks and webhooks

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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.

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.

"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. If the filter is omitted, no callbacks are sent.

Available values depend on the service — see the per-service filter tables below.

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.

"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, 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.

Available filter values by service

EviSMS

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

EviNotice

EviPost

EviSign

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.

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 Identifier. Retries of the same event keep the same identifier.
• 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.

These fields appear inside AdditionalData for EviMail and EviNotice:

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

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

AdditionalData — event-specific fields

Depending on the event type, additional fields are included.

EviNotice, EviMail, EviSMS:

EviPost:

Example payloads

EviMail — Sent event

{
  "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\"}"
  }
}

EviNotice — Received event

{
  "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).

{
  "Identifier": "1234",
  "Kind": "AffidavitPublished",
  "Date": "2026-01-22T12:46:32.4830752+01:00",
  "EvidenceId": "2aca3ea149f943879726a87000c1f704",
  "EvidenceType": "eviPost",
  "Site": "my-site",
  "Owner": null,
  "OwnerEmail": "sender@example.com",
  "AdditionalData": {
    "Sender": "Sender Name",
    "Recipient": "Recipient Name",
    "LookupKey": "order-12345",
    "State": "Closed",
    "CreationDate": "2026-01-22T12:46:12.3113880+01:00",
    "AffidavitId": "000c1f7042aca3ea149f943879726a87",
    "AffidavitName": "Certification of postal communication (upon request)",
    "RequestId": "79726a87000c1f7042aca3ea149f9438"
  }
}

AffidavitKind is not currently emitted for EviPost affidavit callbacks. 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.

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.

{
  "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 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 Identifier with the received event and prevent repeated business actions for that identifier. This is idempotent processing: receiving the same callback twice has the same effect as receiving it once. Make the duplicate check safe when requests arrive concurrently. For example, two deliveries of the same Closed callback should not create two follow-up tasks.

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.

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 Identifier for duplicate detection 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.

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

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 Sent callbacks, Comments on EviMail Replied callbacks).

For acknowledgement, duplicate detection, and correlation, follow 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.

Related

• API reference overview
• Integration workflows
• Security and authentication
• Performance and scaling
• EviSMS API
• EviMail API
• EviNotice API
• EviPost API
• States and outcomes