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

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 the time of submission, using three fields in the Submit request body.

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 state names that should trigger a callback. Only transitions to the listed states will fire a notification. If 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 filter value and the reply state is reported as RepliedOn in the Query response, but the EviSMS pipeline does not currently emit a Replied callback — do not rely on it for push notifications. (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.

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

Return 2xx immediately, process asynchronously. Acknowledge the callback as fast as possible — write the raw body to a queue or durable store before doing any business logic. If your processing takes too long, the platform may time out and retry, producing duplicate deliveries.

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.

Deduplicate by Identifier. The platform retries on timeout or non-2xx. Your handler will receive the same callback more than once in failure scenarios. Deduplicate on the Identifier field — all retries for the same event carry the same value.

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.

Use PushNotificationExtraData as a correlation value. The free-text string you set at submit time is echoed back in every callback inside AdditionalData.ExtraData. You can set a hard-to-guess value here (for example, a UUID you generate at submit time and store alongside the eviId) and verify it on receipt. This does not replace proper authentication but adds a lightweight consistency check.

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 documentation
• Integration workflows
• Security and authentication
• Performance and scaling
• EviSMS API
• EviMail API
• EviNotice API
• EviPost API
• States and outcomes