Delivery receipts

A 202 Accepted from POST /v1/events/trigger indicates that Nervly accepted the notification and durably enqueued it onto JetStream. Delivery receipts determine what happened next.

Checking delivery status

At launch, Nervly supports two primary methods for customers to inspect delivery status:

1. Polling via API & SDK

You can query any event by its ID using the public status endpoint:

curl https://api.nervly.io/v1/events/evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8 \
  -H "Authorization: Bearer $NERVLY_API_KEY"

{
  "event_id": "evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8",
  "event_name": "order-confirmed",
  "subscriber_id": "sub_4920a",
  "status": "DELIVERED",
  "channel": "sms",
  "provider": "termii",
  "priority": 3,
  "attempts": 1,
  "cost_micro_usd": 5000,
  "test_mode": false,
  "variables_keys": ["orderId", "amount"],
  "created_at": "2026-09-11T21:00:00.123Z",
  "updated_at": "2026-09-11T21:00:01.456Z"
}

Or with the official TypeScript SDK (@nervly/sdk):

import { Nervly } from '@nervly/sdk';

const nervly = new Nervly({ apiKey: process.env.NERVLY_API_KEY });
const receipt = await nervly.events.get('evt_9c4f1a2b3d5e6f708192a3b4c5d6e7f8');

console.log(`Status: ${receipt.status}, Provider: ${receipt.provider}, Cost: $${receipt.cost_micro_usd / 1e6}`);

2. Live stream in the dashboard

In app.nervly.io/messages, your team can search, filter, and inspect deliveries with real-time status badges (DELIVERED, FAILED, SUPPRESSED). Clicking any message opens the drawer to display the chronological delivery timeline in order.

Outbound webhooks roadmap

Nervly provides immediate status polling via GET /v1/events/{eventId} at launch. Direct outbound webhooks that push delivery status events to your own HTTP endpoints are not part of the launch surface — they are scheduled for Month 6 or later. This is product sequencing, not an architecture blocker (ADR-010 covers deploy topology, not webhooks). We deferred direct outbound webhooks to get signature rotation, dead-letter retry queues, and replay protection right without rushing the launch.

What is on the launch surface is the local CLI's forwarding tunnel: nervly forward webhooks --to <url> (part of @nervly/cli) dials out to a Nervly-operated relay, the platform posts your real delivery-status events down the established tunnel, and the CLI re-signs each event locally for your receiver. That path delivers real delivery events at v1 without an inbound endpoint on your side and without an assumed platform-signed outbound scheme. It is a consumer of the delivery-events stream described below — not a second webhook product. Do not build against an assumed direct outbound signature scheme yet; this page will document it when direct delivery ships.

Inbound provider callbacks

The webhook surface Nervly operates today is inbound. When a downstream provider (Termii, Resend, ZeptoMail, Infobip, Twilio, …) finishes a delivery, it sends the outcome back to:

POST https://api.nervly.io/v1/webhooks/{provider}

Authentication on this route is by signature, not API key — providers cannot present your bearer token — so it sits outside the authenticated API surface. Nervly authenticates the provider's callback against the raw request body before it parses any JSON — a native provider-issued signature where the provider has one, otherwise a platform-configured shared-secret header — then normalises the callback into one receipt shape. A provider name outside the accepted set is refused 404: there is no unauthenticated catch-all.

The secret the signature is checked against is your workspace's own signing secret for that provider. In the console, open Providers, and on the provider card set (or rotate) its Webhook secret — the value issued by that provider for the webhook endpoint (for SendGrid, the base64 verification public key SendGrid hands you). It is write-only: the console and the API return only a masked hint, never the value. Nervly looks the secret up for the workspace the callback belongs to and verifies the raw body against it. Platform-operated providers (where Nervly runs the provider account) verify against the platform's deployment-wide secret when the workspace is on the shared floor; a workspace with a provisioned child account for that provider verifies against the child's own secret, with no fallback to the shared secret. A callback that cannot be matched to a secret — or that fails verification — is rejected 401 and never parsed. When you rotate a secret, the previous value keeps verifying for a 24-hour window so callbacks already in flight with the old secret are not dropped.

Provider	Signature header	Algorithm	Signed content	Encoding
Termii	X-Termii-Signature	HMAC-SHA256, secret as UTF-8 bytes	raw request body	lowercase hex
Resend (Svix)	svix-signature (+ svix-id, svix-timestamp)	HMAC-SHA256, base64-decoded whsec_… secret	{svix-id}.{svix-timestamp}.{body}	base64, v1, prefix
ZeptoMail	producer-signature	HMAC-SHA256, auth key as UTF-8 bytes	raw request body	base64 (ts=…;s=…;s-algorithm=HmacSHA256)
Infobip	X-Hub-Signature	HMAC-SHA256, secret as UTF-8 bytes	raw request body	base64 or hex (optional sha256= prefix)
Twilio	X-Twilio-Signature	HMAC-SHA1 (Twilio's RequestValidator)	request URL followed by sorted form parameters	base64
Sinch	X-Sinch-Signature	HMAC-SHA256, secret as UTF-8 bytes	raw request body	hex or base64
WhatsApp (Meta)	X-Hub-Signature-256	HMAC-SHA256, app secret as UTF-8 bytes	raw request body	hex, sha256= prefix
Africa's Talking	X-AfricasTalking-Signature	HMAC-SHA256, platform-configured shared secret	raw request body	hex
Sendchamp	X-Sendchamp-Signature	HMAC-SHA256, platform-configured shared secret	raw request body	hex
Postmark	X-Postmark-Signature	HMAC-SHA256, platform-configured shared secret	raw request body	hex
SendGrid	X-Twilio-Email-Event-Webhook-Signature (+ X-Twilio-Email-Event-Webhook-Timestamp)	ECDSA P-256 over SHA256(timestamp ‖ body), with SendGrid's verification public key	timestamp header string followed by the raw request body	base64 ASN.1 DER
Cloudflare (platform Worker forward — see below)	X-Nervly-Cloudflare-Signature	HMAC-SHA256, CLOUDFLARE_WEBHOOK_SECRET as UTF-8 bytes	raw request body	lowercase hex, optional sha256= prefix

Africa's Talking, Sendchamp and Postmark do not sign their callbacks natively; for those the header is a platform-configured shared-secret control (a value injected at the operator's callback relay or by the provider's custom-header setting), verified over the raw body exactly like a native scheme. SendGrid's signature is a genuine provider-issued ECDSA signature verified with the public key from its Event Webhook settings.

Every timestamped scheme (Svix, ZeptoMail, Termii's optional X-Termii-Timestamp, and SendGrid's …-Timestamp) enforces a five-minute replay window. Twilio's, Sinch's, Africa's Talking's, Sendchamp's and Postmark's schemes carry no timestamp; replay is bounded by the durable receipt dedupe Nervly applies downstream, so a replayed callback is a no-op.

Cloudflare: forwarded by the platform's Worker

Cloudflare Email does not sign delivery callbacks itself. Its Email Sending lifecycle events (delivered, deferred, bounced, failed, rejected, complained) are published to a Cloudflare Queue through an Event Subscription. A Go service outside the Cloudflare account cannot consume that Queue directly, so the platform runs a small Cloudflare Worker (nervly-email-events) that consumes the Queue, HMAC-signs each event with the shared CLOUDFLARE_WEBHOOK_SECRET, and forwards it to POST /v1/webhooks/cloudflare.

The gateway verifies that signature on the raw body (the X-Nervly-Cloudflare-Signature row above), then normalises the event like any other receipt: delivered becomes DELIVERED; a hard bounce becomes SUPPRESSED and a spam complaint becomes COMPLAINED, both recording the recipient in the suppression registry; deferred and a soft bounce become the non-terminal BOUNCED_SOFT; and failed and rejected become terminal FAILED. The Worker's deployment notes, event vocabulary and retry/DLQ behaviour live alongside it at nervly-base/infrastructure/cloudflare/workers/email-events/README.md.

Verify a raw-body HMAC-SHA256 signature

The rule that matters most: verify the raw, unparsed request body bytes. Re-serialising a parsed object (JSON.stringify(JSON.parse(body)), json.dumps(json.loads(body))) can reorder keys, change whitespace, and rewrite Unicode escapes, so the HMAC will not match even though the JSON is equivalent. Read the body as bytes, verify, then decode.

The examples below implement the Svix scheme — the one behind Resend and the richest of the set: it signs {svix-id}.{svix-timestamp}.{body} with the base64-decoded secret and compares base64 digests in constant time. To adapt to Termii, sign the raw body with the UTF-8 secret and hex-encode the digest; for ZeptoMail or Infobip, keep the raw body but use the encoding in the table above. Every snippet rejects a stale timestamp and compares the candidate in constant time rather than with == or .equals().

cURL

HMAC-SHA256 over {id}.{timestamp}.{body} with the base64-decoded secret:

#!/usr/bin/env bash
set -euo pipefail

# From the request: `svix-id`, `svix-timestamp` and `svix-signature` headers.
SVIX_ID="${SVIX_ID:?set from the svix-id header}"
SVIX_TIMESTAMP="${SVIX_TIMESTAMP:?set from the svix-timestamp header}"
SVIX_SIGNATURE="${SVIX_SIGNATURE:?set from the svix-signature header}"
SVIX_SECRET="${SVIX_WEBHOOK_SECRET:?set to your whsec_… webhook secret}"

# The raw body exactly as it arrived — read it as bytes, never re-encode it.
RAW_BODY="$(cat payload.json)"

EXPECTED="$(printf '%s.%s.%s' "$SVIX_ID" "$SVIX_TIMESTAMP" "$RAW_BODY" |
  openssl dgst -sha256 -mac HMAC \
    -macopt "hexkey:$(printf '%s' "${SVIX_SECRET#whsec_}" | base64 -d | xxd -p -c 256)" \
    -binary | base64 | tr -d '\n')"

# Reject a stale timestamp (five-minute window) before trusting the MAC.
NOW="$(date +%s)"
if ((NOW - SVIX_TIMESTAMP > 300 || SVIX_TIMESTAMP - NOW > 300)); then
  echo "svix-timestamp outside the five-minute tolerance" >&2
  exit 1
fi

# Constant-time-ish compare: fold every byte difference into `diff` and decide
# once at the end, so the loop never short-circuits on the first mismatch.
CANDIDATE="${SVIX_SIGNATURE#v1,}"
diff=0
[[ "${#EXPECTED}" -eq "${#CANDIDATE}" ]] || diff=1
for ((i = 0; i < ${#EXPECTED} && i < ${#CANDIDATE}; i++)); do
  diff=$((diff | ($(printf '%d' "'${EXPECTED:i:1}") ^ $(printf '%d' "'${CANDIDATE:i:1}"))))
done
if ((diff != 0)); then
  echo "invalid webhook signature" >&2
  exit 1
fi

Shell arithmetic is a convenience, not a hardened crypto runtime — production receivers should use one of the language runtimes below, whose standard libraries expose an OS-backed constant-time compare.

Node.js / TypeScript

import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_SECONDS = 300;

/**
 * Verify a Svix-signed provider callback.
 * `rawBody` must be the exact bytes received — read it before `JSON.parse`.
 */
export function verifySvixSignature(options: {
  secret: string;
  svixId: string;
  svixTimestamp: string;
  svixSignature: string;
  rawBody: Buffer;
  nowSeconds?: number;
}): boolean {
  const { secret, svixId, svixTimestamp, svixSignature, rawBody } = options;
  const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);

  const timestamp = Number(svixTimestamp);
  if (!Number.isInteger(timestamp) || Math.abs(now - timestamp) > TOLERANCE_SECONDS) {
    return false;
  }

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const signedContent = Buffer.concat([Buffer.from(`${svixId}.${svixTimestamp}.`), rawBody]);
  const expected = createHmac('sha256', key).update(signedContent).digest('base64');

  return svixSignature
    .split(' ')
    .filter((part) => part.startsWith('v1,'))
    .some((part) => {
      const candidate = Buffer.from(part.slice(3), 'utf8');
      const digest = Buffer.from(expected, 'utf8');
      return candidate.length === digest.length && timingSafeEqual(candidate, digest);
    });
}

Python

import base64
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_svix_signature(
    secret: str,
    svix_id: str,
    svix_timestamp: str,
    svix_signature: str,
    raw_body: bytes,
) -> bool:
    """Verify a Svix-signed callback. ``raw_body`` is the exact bytes received."""
    try:
        timestamp = int(svix_timestamp)
    except ValueError:
        return False
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed_content = f"{svix_id}.{svix_timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed_content, hashlib.sha256).digest()).decode()

    return any(
        hmac.compare_digest(candidate, expected)
        for part in svix_signature.split(" ")
        if part.startswith("v1,")
        for candidate in [part[3:]]
    )

Go

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"crypto/subtle"
	"encoding/base64"
	"strconv"
	"strings"
	"time"
)

const svixTolerance = 5 * time.Minute

// verifySvixSignature checks a Svix-signed callback. rawBody is the exact bytes
// received — read it before decoding JSON.
func verifySvixSignature(secret, svixID, svixTimestamp, svixSignature string, rawBody []byte) bool {
	timestamp, err := strconv.ParseInt(svixTimestamp, 10, 64)
	if err != nil {
		return false
	}
	if delta := time.Since(time.Unix(timestamp, 0)); delta > svixTolerance || delta < -svixTolerance {
		return false
	}

	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	if err != nil {
		return false
	}

	mac := hmac.New(sha256.New, key)
	mac.Write([]byte(svixID + "." + svixTimestamp + "."))
	mac.Write(rawBody)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))

	for _, part := range strings.Fields(svixSignature) {
		candidate, ok := strings.CutPrefix(part, "v1,")
		if !ok {
			continue
		}
		if subtle.ConstantTimeCompare([]byte(candidate), []byte(expected)) == 1 {
			return true
		}
	}
	return false
}

PHP

<?php

declare(strict_types=1);

const TOLERANCE_SECONDS = 300;

/**
 * Verify a Svix-signed callback. $rawBody is the exact bytes received — read
 * php://input as a string and verify it before json_decode().
 */
function verify_svix_signature(
    string $secret,
    string $svixId,
    string $svixTimestamp,
    string $svixSignature,
    string $rawBody,
): bool {
    if (!ctype_digit($svixTimestamp)) {
        return false;
    }
    if (abs(time() - (int) $svixTimestamp) > TOLERANCE_SECONDS) {
        return false;
    }

    $secretText = str_starts_with($secret, 'whsec_') ? substr($secret, strlen('whsec_')) : $secret;
    $key = base64_decode($secretText, true);
    if ($key === false) {
        return false;
    }

    $expected = base64_encode(hash_hmac('sha256', $svixId . '.' . $svixTimestamp . '.' . $rawBody, $key, true));

    foreach (explode(' ', $svixSignature) as $part) {
        if (str_starts_with($part, 'v1,') && hash_equals($expected, substr($part, 3))) {
            return true;
        }
    }

    return false;
}

Rust

use base64::Engine;
use hmac::{Hmac, Mac};
use sha2::Sha256;
use subtle::ConstantTimeEq;

type HmacSha256 = Hmac<Sha256>;

const TOLERANCE_SECONDS: i64 = 300;

/// Verify a Svix-signed callback. `raw_body` is the exact bytes received — read
/// it before deserialising JSON.
pub fn verify_svix_signature(
    secret: &str,
    svix_id: &str,
    svix_timestamp: &str,
    svix_signature: &str,
    raw_body: &[u8],
    now_sec: i64,
) -> bool {
    let timestamp: i64 = match svix_timestamp.parse() {
        Ok(value) => value,
        Err(_) => return false,
    };
    if (now_sec - timestamp).abs() > TOLERANCE_SECONDS {
        return false;
    }

    let secret_text = secret.strip_prefix("whsec_").unwrap_or(secret);
    let key = match base64::engine::general_purpose::STANDARD.decode(secret_text) {
        Ok(bytes) => bytes,
        Err(_) => return false,
    };

    let mut mac = match HmacSha256::new_from_slice(&key) {
        Ok(mac) => mac,
        Err(_) => return false,
    };
    mac.update(svix_id.as_bytes());
    mac.update(b".");
    mac.update(svix_timestamp.as_bytes());
    mac.update(b".");
    mac.update(raw_body);
    let expected = base64::engine::general_purpose::STANDARD.encode(mac.finalize().into_bytes());

    svix_signature
        .split_whitespace()
        .filter_map(|part| part.strip_prefix("v1,"))
        .any(|candidate| candidate.as_bytes().ct_eq(expected.as_bytes()).into())
}

Java

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class WebhookSignature {
    private static final String HMAC_SHA256 = "HmacSHA256";
    private static final long TOLERANCE_SECONDS = 300;

    /**
     * Verify a Svix-signed callback. rawBody is the exact bytes received — read
     * the request body as byte[] and verify before any JSON decoding.
     */
    public static boolean verifySvixSignature(
        String secret, String svixId, String svixTimestamp, String svixSignature, byte[] rawBody
    ) throws Exception {
        long timestamp = Long.parseLong(svixTimestamp);
        if (Math.abs(Instant.now().getEpochSecond() - timestamp) > TOLERANCE_SECONDS) {
            return false;
        }

        byte[] key = Base64.getDecoder().decode(secret.replaceFirst("^whsec_", ""));
        Mac mac = Mac.getInstance(HMAC_SHA256);
        mac.init(new SecretKeySpec(key, HMAC_SHA256));
        mac.update((svixId + "." + svixTimestamp + ".").getBytes(StandardCharsets.UTF_8));
        mac.update(rawBody);
        byte[] expected = Base64.getEncoder().encodeToString(mac.doFinal()).getBytes(StandardCharsets.UTF_8);

        for (String part : svixSignature.split(" ")) {
            if (!part.startsWith("v1,")) {
                continue;
            }
            byte[] candidate = part.substring(3).getBytes(StandardCharsets.UTF_8);
            if (candidate.length == expected.length && MessageDigest.isEqual(candidate, expected)) {
                return true;
            }
        }
        return false;
    }
}

C#

using System;
using System.Security.Cryptography;
using System.Text;

public static class WebhookSignature
{
    private const int ToleranceSeconds = 300;

    /// <summary>
    /// Verify a Svix-signed callback. rawBody is the exact bytes received — read
    /// the request body as byte[] and verify before any JSON deserialisation.
    /// </summary>
    public static bool VerifySvixSignature(
        string secret, string svixId, string svixTimestamp, string svixSignature, byte[] rawBody)
    {
        if (!long.TryParse(svixTimestamp, out long timestamp))
        {
            return false;
        }
        if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - timestamp) > ToleranceSeconds)
        {
            return false;
        }

        string secretText = secret.StartsWith("whsec_", StringComparison.Ordinal)
            ? secret.Substring("whsec_".Length)
            : secret;
        byte[] key = Convert.FromBase64String(secretText);

        byte[] prefix = Encoding.UTF8.GetBytes($"{svixId}.{svixTimestamp}.");
        byte[] signedContent = new byte[prefix.Length + rawBody.Length];
        Buffer.BlockCopy(prefix, 0, signedContent, 0, prefix.Length);
        Buffer.BlockCopy(rawBody, 0, signedContent, prefix.Length, rawBody.Length);

        using var hmac = new HMACSHA256(key);
        byte[] expected = Encoding.ASCII.GetBytes(Convert.ToBase64String(hmac.ComputeHash(signedContent)));

        foreach (string part in svixSignature.Split(' ', StringSplitOptions.RemoveEmptyEntries))
        {
            if (!part.StartsWith("v1,", StringComparison.Ordinal))
            {
                continue;
            }
            byte[] candidate = Encoding.ASCII.GetBytes(part.Substring(3));
            if (candidate.Length == expected.Length
                && CryptographicOperations.FixedTimeEquals(candidate, expected))
            {
                return true;
            }
        }
        return false;
    }
}

Ruby

require 'base64'
require 'openssl'

TOLERANCE_SECONDS = 300

# Verify a Svix-signed callback. +raw_body+ is the exact bytes received — read
# it before JSON.parse.
def verify_svix_signature(secret:, svix_id:, svix_timestamp:, svix_signature:, raw_body:)
  timestamp = Integer(svix_timestamp, 10)
  return false if (Time.now.to_i - timestamp).abs > TOLERANCE_SECONDS

  key = Base64.strict_decode64(secret.delete_prefix('whsec_'))
  signed_content = "#{svix_id}.#{svix_timestamp}."
  expected = Base64.strict_encode64(
    OpenSSL::HMAC.digest('SHA256', key, signed_content + raw_body)
  )

  svix_signature.split(' ').any? do |part|
    next false unless part.start_with?('v1,')

    candidate = part.delete_prefix('v1,')
    # fixed_length_secure_compare never short-circuits on the first bad byte.
    expected.bytesize == candidate.bytesize &&
      OpenSSL.fixed_length_secure_compare(expected, candidate)
  end
rescue ArgumentError
  false
end

Swift

import CryptoKit
import Foundation

private let toleranceSeconds: TimeInterval = 300

/// Verify a Svix-signed callback. `rawBody` is the exact bytes received — read
/// the request body as `Data` and verify before any `JSONDecoder` call.
func verifySvixSignature(
    secret: String,
    svixId: String,
    svixTimestamp: String,
    svixSignature: String,
    rawBody: Data,
    now: Date = Date()
) -> Bool {
    guard let timestamp = TimeInterval(svixTimestamp),
          abs(now.timeIntervalSince1970 - timestamp) <= toleranceSeconds else {
        return false
    }

    let secretText = secret.hasPrefix("whsec_")
        ? String(secret.dropFirst("whsec_".count))
        : secret
    guard let key = Data(base64Encoded: secretText) else { return false }

    var signedContent = Data("\(svixId).\(svixTimestamp).".utf8)
    signedContent.append(rawBody)
    let code = HMAC<SHA256>.authenticationCode(for: signedContent, using: SymmetricKey(data: key))
    let expected = Data(code).base64EncodedString()

    return svixSignature.split(separator: " ").contains { part in
        guard part.hasPrefix("v1,") else { return false }
        return constantTimeEquals(String(part.dropFirst(3)), expected)
    }
}

/// Compares two strings without short-circuiting on the first differing byte.
private func constantTimeEquals(_ lhs: String, _ rhs: String) -> Bool {
    let lhsBytes = Array(lhs.utf8)
    let rhsBytes = Array(rhs.utf8)
    guard lhsBytes.count == rhsBytes.count else { return false }
    var difference: UInt8 = 0
    for index in lhsBytes.indices {
        difference |= lhsBytes[index] ^ rhsBytes[index]
    }
    return difference == 0
}

Golden test vector

Reproduce this vector by hand to confirm your verifier implements the algorithm above. npm run check:snippets recomputes it on every build, so a wrong algorithm or mismatched digest fails the gate by name.

NERVLY-WEBHOOK-GOLDEN-VECTOR
secret=whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
id=msg_p5jXN8AQM9LWM0D9d97iMH2mit5o3
timestamp=1732166400
body={"type":"email.delivered","data":{"email_id":"49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"}}
signature=v1,BZ/abGUZl58eXnR/GOTaiSRh4cRt2bd9J6XCdvDRItY=

The signature is the base64 HMAC-SHA256 of the exact {id}.{timestamp}.{body} string assembled from the lines above, keyed with the base64-decoded whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw. Change any byte of the body and the digest changes.

Normalized receipt payload

Once a callback's signature verifies, Nervly normalises every provider dialect into a single TelemetryReceiptEvent, published as JSON on its internal telemetry stream and described by the public API reference:

{
  "provider": "resend",
  "message_id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794",
  "recipient": "user@example.com",
  "status": "DELIVERED",
  "timestamp": "2026-09-17T02:22:00Z",
  "raw_event_id": "dlr_1a2b3c4d5e6f70819",
  "workspace_id": "ws_9f2c1d",
  "bounce_reason": null
}

Field	Required	Meaning
provider	yes	Provider that reported the receipt (termii, resend, zeptomail, infobip, twilio, sinch, africastalking, whatsapp, sendchamp, postmark, sendgrid, cloudflare).
message_id	yes	The provider's own identifier for the message.
recipient	yes	Recipient address or token.
status	yes	Delivery outcome: DELIVERED, BOUNCED_HARD, BOUNCED_SOFT, or COMPLAINED.
timestamp	yes	ISO 8601 / RFC 3339 time the event occurred.
raw_event_id	yes	Nervly's identifier for this receipt (dlr_…).
workspace_id	no	Workspace the receipt belongs to, when known.
bounce_reason	no	Diagnostic text for a bounce or complaint.

This normalized event is the shape on Nervly's telemetry stream and in the API reference; it is not yet delivered directly to customer HTTP endpoints (see the outbound webhooks roadmap above) — at launch it reaches your machine through the local CLI's forwarding tunnel, nervly forward webhooks. The decoders below show how to read it — useful if you self-host Nervly or consume its telemetry, and directly applicable to the payload the CLI forwards or once direct outbound webhooks ship.

cURL

# jq reads the normalized receipt; no re-serialization is involved.
echo "$RAW_BODY" | jq -r '"\(.raw_event_id) \(.status) \(.provider) \(.timestamp)"'

Node.js / TypeScript

type DeliveryStatus = 'DELIVERED' | 'BOUNCED_HARD' | 'BOUNCED_SOFT' | 'COMPLAINED';

interface TelemetryReceiptEvent {
  provider: string;
  message_id: string;
  recipient: string;
  status: DeliveryStatus;
  timestamp: string;
  raw_event_id: string;
  workspace_id?: string | null;
  bounce_reason?: string | null;
}

export function ingestReceipt(rawBody: string): void {
  const receipt = JSON.parse(rawBody) as TelemetryReceiptEvent;
  console.log(
    `receipt=${receipt.raw_event_id} status=${receipt.status} ` +
      `provider=${receipt.provider} at=${receipt.timestamp}`,
  );
}

Python

import json

DELIVERY_OUTCOMES = ("DELIVERED", "BOUNCED_HARD", "BOUNCED_SOFT", "COMPLAINED")


def ingest_receipt(raw_body: bytes) -> None:
    receipt = json.loads(raw_body)
    status = receipt["status"]
    if status not in DELIVERY_OUTCOMES:
        raise ValueError(f"unexpected delivery status: {status}")
    print(
        f"receipt={receipt['raw_event_id']} status={status} "
        f"provider={receipt['provider']} at={receipt['timestamp']}"
    )

Go

package main

import (
	"encoding/json"
	"fmt"
)

type TelemetryReceiptEvent struct {
	Provider     string  `json:"provider"`
	MessageID    string  `json:"message_id"`
	Recipient    string  `json:"recipient"`
	Status       string  `json:"status"`
	Timestamp    string  `json:"timestamp"`
	RawEventID   string  `json:"raw_event_id"`
	WorkspaceID  *string `json:"workspace_id,omitempty"`
	BounceReason *string `json:"bounce_reason,omitempty"`
}

func ingestReceipt(rawBody []byte) error {
	var receipt TelemetryReceiptEvent
	if err := json.Unmarshal(rawBody, &receipt); err != nil {
		return err
	}
	fmt.Printf("receipt=%s status=%s provider=%s at=%s\n",
		receipt.RawEventID, receipt.Status, receipt.Provider, receipt.Timestamp)
	return nil
}

PHP

<?php

declare(strict_types=1);

/**
 * @return array{provider: string, message_id: string, recipient: string,
 *               status: string, timestamp: string, raw_event_id: string}
 */
function ingest_receipt(string $rawBody): array
{
    $receipt = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
    printf(
        "receipt=%s status=%s provider=%s at=%s\n",
        $receipt['raw_event_id'],
        $receipt['status'],
        $receipt['provider'],
        $receipt['timestamp'],
    );

    return $receipt;
}

Rust

use serde::Deserialize;

#[derive(Debug, Deserialize)]
pub struct TelemetryReceiptEvent {
    pub provider: String,
    pub message_id: String,
    pub recipient: String,
    pub status: String,
    pub timestamp: String,
    pub raw_event_id: String,
    pub workspace_id: Option<String>,
    pub bounce_reason: Option<String>,
}

pub fn ingest_receipt(raw_body: &[u8]) -> Result<TelemetryReceiptEvent, serde_json::Error> {
    let receipt: TelemetryReceiptEvent = serde_json::from_slice(raw_body)?;
    println!(
        "receipt={} status={} provider={} at={}",
        receipt.raw_event_id, receipt.status, receipt.provider, receipt.timestamp
    );
    Ok(receipt)
}

Java

import java.time.OffsetDateTime;

public class ReceiptIngest {
    public record DeliveryReceipt(
        String provider,
        String messageId,
        String recipient,
        String status,
        OffsetDateTime occurredAt,
        String rawEventId
    ) {}

    public static DeliveryReceipt ingest(String rawBody) {
        String timestamp = jsonString(rawBody, "timestamp");
        return new DeliveryReceipt(
            jsonString(rawBody, "provider"),
            jsonString(rawBody, "message_id"),
            jsonString(rawBody, "recipient"),
            jsonString(rawBody, "status"),
            timestamp == null ? null : OffsetDateTime.parse(timestamp),
            jsonString(rawBody, "raw_event_id")
        );
    }

    /**
     * Reads one flat string field from the normalized receipt. This keeps the
     * example dependency-free on a bare JDK; use a JSON library (Jackson, Gson)
     * for untrusted or nested payloads.
     */
    private static String jsonString(String json, String key) {
        int at = json.indexOf('"' + key + "\":");
        if (at < 0) {
            return null;
        }
        int i = at + key.length() + 3;
        while (i < json.length() && Character.isWhitespace(json.charAt(i))) {
            i++;
        }
        if (i >= json.length() || json.charAt(i) != '"') {
            return null;
        }
        StringBuilder out = new StringBuilder();
        for (i++; i < json.length(); i++) {
            char c = json.charAt(i);
            if (c == '\\' && i + 1 < json.length()) {
                char next = json.charAt(++i);
                switch (next) {
                    case 'n' -> out.append('\n');
                    case 't' -> out.append('\t');
                    case 'r' -> out.append('\r');
                    case 'b' -> out.append('\b');
                    case 'f' -> out.append('\f');
                    default -> out.append(next);
                }
            } else if (c == '"') {
                return out.toString();
            } else {
                out.append(c);
            }
        }
        return null;
    }
}

C#

using System;
using System.Text.Json;
using System.Text.Json.Serialization;

public sealed record TelemetryReceiptEvent(
    [property: JsonPropertyName("provider")] string Provider,
    [property: JsonPropertyName("message_id")] string MessageId,
    [property: JsonPropertyName("recipient")] string Recipient,
    [property: JsonPropertyName("status")] string Status,
    [property: JsonPropertyName("timestamp")] string Timestamp,
    [property: JsonPropertyName("raw_event_id")] string RawEventId,
    [property: JsonPropertyName("workspace_id")] string? WorkspaceId,
    [property: JsonPropertyName("bounce_reason")] string? BounceReason);

public static class ReceiptIngest
{
    public static void Ingest(byte[] rawBody)
    {
        TelemetryReceiptEvent receipt = JsonSerializer.Deserialize<TelemetryReceiptEvent>(rawBody)
            ?? throw new InvalidOperationException("empty receipt");
        Console.WriteLine(
            $"receipt={receipt.RawEventId} status={receipt.Status} " +
            $"provider={receipt.Provider} at={receipt.Timestamp}");
    }
}

Ruby

require 'json'
require 'time'

DELIVERY_OUTCOMES = %w[DELIVERED BOUNCED_HARD BOUNCED_SOFT COMPLAINED].freeze

def ingest_receipt(raw_body)
  receipt = JSON.parse(raw_body)
  status = receipt.fetch('status')
  raise ArgumentError, "unexpected delivery status: #{status}" unless DELIVERY_OUTCOMES.include?(status)

  occurred_at = Time.iso8601(receipt.fetch('timestamp'))
  puts "receipt=#{receipt.fetch('raw_event_id')} status=#{status} " \
       "provider=#{receipt.fetch('provider')} at=#{occurred_at.iso8601}"
end

Swift

import Foundation

struct TelemetryReceiptEvent: Decodable {
    let provider: String
    let messageId: String
    let recipient: String
    let status: String
    let timestamp: String
    let rawEventId: String
    let workspaceId: String?
    let bounceReason: String?

    enum CodingKeys: String, CodingKey {
        case provider, recipient, status, timestamp
        case messageId = "message_id"
        case rawEventId = "raw_event_id"
        case workspaceId = "workspace_id"
        case bounceReason = "bounce_reason"
    }
}

func ingestReceipt(rawBody: Data) throws {
    let receipt = try JSONDecoder().decode(TelemetryReceiptEvent.self, from: rawBody)
    print(
        "receipt=\(receipt.rawEventId) status=\(receipt.status) " +
        "provider=\(receipt.provider) at=\(receipt.timestamp)")
}

Durability and telemetry

After dispatch, the worker records delivery state and telemetry:

• It updates the message's status (DELIVERED, FAILED, SUPPRESSED), attempt count, provider, and final channel.
• It appends an immutable timeline step for each state transition, including error diagnostics.
• It aggregates daily message counts and costs per workspace, channel, and provider so analytics queries do not scan the full message history.

Every record is scoped to your workspace; none of it is visible to another tenant.

Next

• Reading message status
• Priorities and routing
• Failover and circuit breakers