Client receipts
Receipts let the app tell your server that a push reached it (“received”) or was opened. They are optional, off by default, and need the durable delivery profile.
| Enable | mobile-push.receipts.enabled = true (env MOBILE_PUSH_RECEIPTS_ENABLED=true) and mobile-push.delivery.profile = durable (env MOBILE_PUSH_DELIVERY_PROFILE=durable) |
| Migration tag | the ledger migrations: php artisan vendor:publish --tag=mobile-push-migrations-ledger then php artisan migrate (or php artisan mobile-push:install; with MOBILE_PUSH_MIGRATIONS_AUTOLOAD=true nothing is published and migrate loads the package files). The third file adds the receipt columns message_id, receipt_marker and the client event columns; all migrations are idempotent |
| Route | POST {prefix}/receipts, default POST /mobile-push/receipts |
With receipts.enabled = true but the light profile, no route is registered and no marker is issued: receipts write to the ledger, which the light profile does not have.
Related pages: outcomes, campaigns, queues and Horizon, security and privacy, configuration, troubleshooting.
What a receipt is, and what it is not
Acceptedmeans the provider accepted the push. It is not delivery.- A receipt proves that the app possesses the marker that was in the payload. It does not prove a human read anything, and it does not prove the notification was displayed.
- iOS and Android do not guarantee that your code runs for every delivered notification. A missing report means “not observed”, never “not delivered”. The package never turns an absence of receipts into a failure.
- Topic, condition and broadcast pushes (and Live Activity pushes) carry no marker: one payload reaches many phones, so there are no individual receipts for them, by design.
The marker is only issued for sends that go through the ledger (->queue() on the durable profile, and campaigns). The synchronous ->send() path writes no ledger row and therefore carries no marker, because a marker without a row to match would be a dead reference.
The marker
Every individual push sent with receipts on carries one extra custom value, mp_r: a top-level key next to aps for APNs, a data entry for FCM (so it counts against the FCM payload size). It is an opaque URL-safe string of about 55 characters: an HMAC over the scope, the sender’s message id for that delivery and an expiry, with a dedicated key ring (independent of the index and encryption keys; several versions verify, the current one signs).
mp_ris reserved: an APNs message whose own custom data uses that key is refused with anInvalidMessageExceptionwhen a marker is added. The marker does not switchmutable-contenton for you.- It is bound to one delivery and expires after
receipts.marker_ttl(default 604800 seconds, 7 days, minimum 60). - The scope used to look the delivery up comes from the verified marker, never from the request: tenant A’s marker can only ever look inside tenant A.
- It is never logged, never echoed back and never put in a cache key (rate limits use a one-way hash). The log sinks are given each issued marker as a runtime secret so it cannot appear in a log line.
- The ledger assigns each delivery a random UUIDv4
message_idat insert; that id is used asapns-idand as the receipt reference, so a delivery whose response was lost can still be matched by its marker.
Key configuration: receipts.keys (map version 1-255 => base64 key of at least 32 bytes; env MOBILE_PUSH_RECEIPTS_KEY fills version 1) and receipts.key_current (MOBILE_PUSH_RECEIPTS_KEY_VERSION, 0 = the highest version). Empty means version 1 is derived from APP_KEY.
The endpoint and its configuration
POST {prefix}/receipts, JSON:
{ "marker": "<mp_r value>", "event": "received", "at": "2026-11-20T10:00:03Z" }
eventisreceivedoropened.atis optional (ISO-8601 with offset); the server clamps it into[delivery creation, now]because phone clocks lie.- A small batch is accepted: a JSON array of such objects, or
{"receipts": [...]}, capped byreceipts.max_batch(default 20).
| Answer | Meaning |
|---|---|
204 |
recorded, or already recorded (idempotent: each event is recorded once per delivery, first write wins; opened before received is fine) |
422 |
not accepted. The body is always the same and never says why: malformed, forged, expired, unknown, or the delivery is not in a state that takes a report. One legitimate case: the report outran the server (the push reached the phone before the server saved the send result). Retry once or twice after a few seconds, then drop it |
429 |
too many reports from this IP or for this marker; Retry-After is set |
Only deliveries in state Accepted or OutcomeUnknown take a report.
Configuration (all under mobile-push.receipts):
| Key | Env | Default | Notes |
|---|---|---|---|
enabled |
MOBILE_PUSH_RECEIPTS_ENABLED |
false |
|
marker_ttl |
MOBILE_PUSH_RECEIPTS_TTL |
604800 |
seconds, at least 60 |
max_batch |
20 |
reports per request | |
route.prefix |
MOBILE_PUSH_RECEIPTS_PREFIX |
mobile-push |
|
route.domain |
null |
serve the route on a dedicated domain | |
route.middleware |
['throttle:mobile-push-receipts'] |
list of middleware | |
rate_limit.per_ip |
120 |
requests per minute per IP, 0 = no limit |
|
rate_limit.per_marker |
10 |
reports per minute per marker, 0 = no limit |
|
keys, key_current |
MOBILE_PUSH_RECEIPTS_KEY, MOBILE_PUSH_RECEIPTS_KEY_VERSION |
derived from APP_KEY, 0 |
see above |
The routes are not registered when your application has cached its routes (route:cache): clear the cache after enabling receipts or changing the prefix.
No authentication by default, and how to add it
The marker is the capability, so the route has no auth middleware by default: the app can report from a Notification Service Extension that has no user session. The package limits abuse with a per-IP limiter (named mobile-push-receipts) and a per-marker limit. If you need a report tied to an authenticated installation, add your own middleware and send the auth header from the app:
// config/mobile-push.php
'receipts' => [
'route' => [
'prefix' => 'mobile-push',
'middleware' => ['throttle:mobile-push-receipts', 'auth:sanctum'],
],
],
Then compare $request->user() with the owner of the delivery in a listener of PushReceivedReported / PushOpenedReported. Those events carry the scope, effect id, delivery id, destination kind and both timestamps, never the token or the marker. A Notification Service Extension usually cannot reach the app’s session: for it, the marker alone is what you have.
The funnel: denominators and coverage
use Padosoft\MobilePush\Laravel\Receipts\ReceiptFunnelReader;
$funnel = app(ReceiptFunnelReader::class)->forEffect($scope, $effectId); // or ->forCampaign($scope, $campaignId)
$funnel->toArray();
The funnel is accepted by the provider -> able to report (carried a marker) -> reported received -> reported opened, always with its denominator:
| Field | Meaning |
|---|---|
accepted |
deliveries the provider accepted (the denominator) |
acceptedWithMarker |
of those, how many carried a marker and could report (coverage = markerCoverage()) |
acceptedWithoutMarker() |
accepted deliveries that could not report at all |
reportedReceived, reportedOpened |
accepted deliveries with a client-reported event (opened is independent of received) |
receivedNotObserved() |
able to report but no received seen: not “not delivered” |
receivedRate(), openedRate() |
reported / able to report: the honest rate, a lower bound of the real one |
receivedOfAccepted(), openedOfAccepted() |
reported / all accepted (includes those that could not report) |
unknownOutcome, unknownReportedReceived, unknownReportedOpened, unknownClientConfirmed |
the unknown-outcome bucket, below |
acceptedOrClientConfirmed() |
accepted + unknown outcomes that the phone confirmed |
Always show the coverage next to a rate. A “received rate of 40%” over 50% marker coverage is a very different statement from the same number over 100%.
use Padosoft\MobilePush\Core\Ledger\ReceiptFunnel;
// Row layout of the deliveries table (only the columns the funnel reads).
$funnel = ReceiptFunnel::fromRows([
['state' => 'accepted', 'receipt_marker' => 1, 'client_received_at' => 1_000, 'client_opened_at' => 1_030],
['state' => 'accepted', 'receipt_marker' => 1, 'client_received_at' => 1_001, 'client_opened_at' => null],
['state' => 'accepted', 'receipt_marker' => 1, 'client_received_at' => null, 'client_opened_at' => null],
['state' => 'accepted', 'receipt_marker' => 0, 'client_received_at' => null, 'client_opened_at' => null], // a topic: no marker
['state' => 'outcome_unknown', 'receipt_marker' => 1, 'client_received_at' => 1_002, 'client_opened_at' => null],
]);
expect($funnel->accepted)->toBe(4)
->and($funnel->acceptedWithMarker)->toBe(3)
->and($funnel->markerCoverage())->toBe(0.75)
->and($funnel->receivedNotObserved())->toBe(1) // not observed, NOT "not delivered"
->and($funnel->unknownClientConfirmed)->toBe(1)
->and($funnel->acceptedOrClientConfirmed())->toBe(5);
Unknown outcomes confirmed by a receipt
When the response to a send was lost, the delivery ends OutcomeUnknown. A receipt for it is evidence that the push did reach the phone, so the report is recorded and counted in the unknown* fields. The provider outcome is not changed: it stays unknown in the ledger and in SendStatus; the client confirmation is a separate, third fact. The funnel keeps the three apart: provider accepted, client-reported received, client-reported opened.
The app-side contract
Fire and forget, with a short timeout. Never block the notification on it. Do not queue reports for days. The Swift and Kotlin below come from src/Laravel/Receipts/CLIENT_CONTRACT.md and were not compiled.
iOS. Received: a Notification Service Extension (UNNotificationServiceExtension) with mutable-content: 1 in the push. Opened: the UNUserNotificationCenterDelegate.
// NotificationService.swift (extension target)
override func didReceive(_ request: UNNotificationRequest,
withContentHandler handler: @escaping (UNNotificationContent) -> Void) {
let content = (request.content.mutableCopy() as? UNMutableNotificationContent) ?? UNMutableNotificationContent()
guard let marker = request.content.userInfo["mp_r"] as? String else { return handler(content) }
Receipts.send(marker: marker, event: "received") { handler(content) } // finish within ~30 s
}
// AppDelegate / delegate (main app)
func userNotificationCenter(_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse,
withCompletionHandler done: @escaping () -> Void) {
if let marker = response.notification.request.content.userInfo["mp_r"] as? String,
response.actionIdentifier == UNNotificationDefaultActionIdentifier {
Receipts.send(marker: marker, event: "opened") { done() }
} else { done() }
}
enum Receipts {
static func send(marker: String, event: String, done: @escaping () -> Void) {
var req = URLRequest(url: URL(string: "https://api.example.com/mobile-push/receipts")!, timeoutInterval: 8)
req.httpMethod = "POST"
req.setValue("application/json", forHTTPHeaderField: "Content-Type")
let at = ISO8601DateFormatter().string(from: Date())
req.httpBody = try? JSONSerialization.data(withJSONObject: ["marker": marker, "event": event, "at": at])
URLSession.shared.dataTask(with: req) { _, _, _ in done() }.resume()
}
}
iOS caveats: the extension runs only for pushes that are visible alerts with mutable-content: 1. It does not run for silent/background pushes, when notifications are turned off for the app, in Focus modes that suppress delivery, or when the system kills the extension for exceeding its time or memory budget. “Opened” is only seen when the user taps the notification itself. Remember to ask for mutable-content on messages that should be able to report (->mutableContent() on the message).
Android. Received: FirebaseMessagingService.onMessageReceived. Opened: the intent behind the notification tap.
class PushService : FirebaseMessagingService() {
override fun onMessageReceived(message: RemoteMessage) {
message.data["mp_r"]?.let { Receipts.send(applicationContext, it, "received") }
// ... show your notification, and put the marker in the tap intent:
// intent.putExtra("mp_r", message.data["mp_r"])
}
}
// In the launched Activity (onCreate / onNewIntent):
intent.getStringExtra("mp_r")?.let { Receipts.send(applicationContext, it, "opened") }
object Receipts {
fun send(context: Context, marker: String, event: String) {
// Prefer WorkManager (network constraint, a few retries) over a bare thread.
val body = JSONObject(mapOf("marker" to marker, "event" to event,
"at" to java.time.Instant.now().toString())).toString()
// POST body as application/json to https://api.example.com/mobile-push/receipts
}
}
Android caveats: with a notification message (not data) delivered while the app is in the background, FCM shows the notification itself and onMessageReceived is not called, so “received” is not observable (use a data message that you display yourself, or accept the gap); the tap then opens your launcher activity with the data in the intent extras. Battery optimisation, “restricted” app standby buckets, force-stop and a user who disabled the notification channel all hide pushes from your code.
How the pieces connect on the server
- On the durable profile the manager hands every ledger send an issuer callback (
ReceiptMarkerIssuer::callback($scope)), and the relay sends each delivery under the ledger’s message id. Nothing to wire when receipts are enabled. - A marker is issued only for individual installations (not topics, conditions, broadcast channels) and not for Live Activity or push-to-start tokens.
PushReceivedReportedandPushOpenedReportedare dispatched once per delivery and event.- Receipts do not depend on the device registry or on notifications; they depend on the ledger.
What was not verified: the endpoint and funnel are exercised with synthetic markers and a fake transport on SQLite. No real device has produced a receipt, and the Swift and Kotlin code was not compiled or run.
This page is generated from docs/receipts.md. To change it, edit that file in the repository, not this site.