Design the backend behind proof of delivery: photo and signature uploads through signed URLs, submissions that survive offline retries, location checks, delivery status events, customer notifications and a lookup for disputes, then build it in Go with Encore.

A proof of delivery feature looks like a photo upload and a status flag, and the first version is often exactly that, a multipart POST to the API server and an UPDATE stops SET status = 'delivered'. The gaps show up later: an upload that times out on the doorstep is sent twice, a stop gets two "delivered" events from two retries, a photo taken 2 km from the address goes unnoticed, and when a customer says the parcel never arrived, support has a status and no evidence.
Proof of delivery is the record that answers that customer: one delivery event per stop with the driver, the device time, the location and the recipient, plus photos and a signature kept in private object storage. This guide designs that backend, with uploads through signed URLs, submissions that are safe to retry, location checks that flag instead of reject, status events for notifications and tracking, and a lookup for disputes. It starts with the data model and a hand-built version on AWS, then builds it in Go with Encore. Quiqup built a scalable logistics platform connecting order sources, fulfillment centers and delivery partners, using Encore, and Pallet built an event-driven AI logistics platform on GCP with Encore.
A delivery event records who delivered, which stop, the outcome, the time on the device when the driver tapped, the time the server received it, the coordinates and the recipient name. Failed attempts are events too, with a reason such as nobody_home or no_access, and they matter in a dispute as much as the delivery does: "we tried at 09:12 and left a card" answers the dispute, and a missing row does not.
Each event points to its artifacts, a photo of the parcel at the door and a signature image when the shipment needs one. The backend refuses a delivery without a photo and refuses a signature-required stop without a signature, so the rule lives in one place instead of in every version of the driver app.
Photos go straight from the phone to object storage, never through the API. The app asks for an upload slot, the backend records a pending artifact for the stop and returns a signed URL valid for 15 minutes, and the app PUTs the image. The API server never holds a 5 MB image in memory, and a slow upload does not tie up a request.
A signed URL is a bearer credential: S3 lets anyone holding one use it multiple times until it expires. Keep the TTL short, keep the bucket private, and turn on versioning. Versioning alone is not enough, because ordinary reads return the latest object, so the completion step records the version ID and support downloads read that version from the API. A second PUT to the same URL then cannot change the evidence already attached to a delivery. The URL does not cap the file size either, so completion also reads the object attributes and refuses anything over 15 MB.
Drivers lose signal in stairwells and basements, and the app queues the submission and retries. The app generates the event ID when the driver taps Complete and sends the same ID on every retry. The insert uses ON CONFLICT (id) DO NOTHING, and a request whose ID is already stored returns the stored result instead of an error, so the app can stop retrying.
Two different submissions for the same stop, from a double tap on two screens, are a separate case. A partial unique index on delivery_events (stop_id) WHERE outcome = 'delivered' allows any number of attempts and exactly one delivery, and the second one gets a conflict that the app can show.
The backend computes the distance between the device coordinates and the geocoded delivery address and stores it on the event. Phones are typically accurate to within about 4.9 m under open sky, and worse near buildings, bridges and trees, and geocoding a large building or a rural address can put the pin far from the door. Rejecting a delivery at 300 m would block drivers at the back entrance of an apartment block, so the event is accepted and flagged above 250 m, and support sees the flag in the lookup.
After the transaction commits, the service publishes a delivery-status event with the stop, the shipment and the outcome. Tracking pages, partner webhooks and the customer notification subscribe to it instead of polling the stops table. SNS with standard SQS queues, the usual AWS setup, can deliver a message more than once, so the notification subscriber inserts the event ID into notifications_sent first and only sends when the insert added a row.
A publish that fails after the commit returns an error to the app, which retries with the same event ID. The retry finds the stored event and returns it, so a missed notification is the cost. If notifications must never be skipped, write the event to an outbox table in the same transaction and publish from there, as described in the shipment tracking pipeline.
Support needs every event for a stop in order, with the driver, the device and server times, the distance flag and the evidence. The lookup is restricted to the support role and returns download URLs that expire after 10 minutes, so a link pasted into a ticket stops working instead of leaving customer doorstep photos public. Keep the device time and the server time separate: a large gap between them is how an event recorded offline and synced later looks, and support should see it.
pod/ prefix.HeadObject calls to check uploads.The parts that decide whether a dispute can be answered, the event model and the checks, are a small share of that list, and most of it is infrastructure that has to change whenever a subscriber or a bucket is added.
Encore is a backend framework for Go with built-in infrastructure, and here the database, the evidence bucket and the delivery-status topic are declared in the same file as the handlers. On deploy to your own AWS account, Encore provisions RDS, S3 and SNS with SQS, as the AWS infrastructure docs describe, and provisions an IAM role for the service.

A coding agent asked to add a "left with neighbour" outcome changes a CHECK constraint and one condition in Go, and encore run gives it Postgres, a local bucket and local Pub/Sub to test the change before it is reviewed.
Run in your terminal to get started locally.
The schema goes in pod/migrations/1_pod.up.sql. Tokens are stored as SHA-256 hashes, and stops are written by your dispatch service, as in the last-mile dispatch backend:
CREATE TABLE api_tokens (
token_hash TEXT PRIMARY KEY, -- SHA-256 of the bearer token
user_id TEXT NOT NULL,
role TEXT NOT NULL CHECK (role IN ('driver', 'support')),
expires_at TIMESTAMPTZ NOT NULL
);
CREATE TABLE stops (
id TEXT PRIMARY KEY,
shipment_id TEXT NOT NULL,
driver_id TEXT,
lat DOUBLE PRECISION NOT NULL, -- geocoded delivery address
lng DOUBLE PRECISION NOT NULL,
signature_required BOOLEAN NOT NULL DEFAULT false,
status TEXT NOT NULL DEFAULT 'out_for_delivery'
CHECK (status IN ('out_for_delivery', 'delivered', 'attempted'))
);
CREATE TABLE pod_artifacts (
id TEXT PRIMARY KEY,
stop_id TEXT NOT NULL REFERENCES stops (id),
kind TEXT NOT NULL CHECK (kind IN ('photo', 'signature')),
object_key TEXT NOT NULL UNIQUE,
status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'attached')),
size_bytes BIGINT,
version_id TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- One row per scan or attempt. The ID comes from the driver app, so an
-- offline retry of the same submission is the same row.
CREATE TABLE delivery_events (
id TEXT PRIMARY KEY,
stop_id TEXT NOT NULL REFERENCES stops (id),
driver_id TEXT NOT NULL,
outcome TEXT NOT NULL CHECK (outcome IN ('delivered', 'attempted')),
reason TEXT, -- for attempts: nobody_home, no_access, refused
recipient_name TEXT,
captured_at TIMESTAMPTZ NOT NULL, -- device clock, when the driver tapped
received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
lat DOUBLE PRECISION,
lng DOUBLE PRECISION,
distance_m INT, -- from the geocoded address
artifact_ids TEXT[] NOT NULL DEFAULT '{}'
);
CREATE UNIQUE INDEX one_delivery_per_stop ON delivery_events (stop_id) WHERE outcome = 'delivered';
CREATE INDEX delivery_events_stop ON delivery_events (stop_id, captured_at);
CREATE TABLE notifications_sent (
event_id TEXT PRIMARY KEY
);
The first part declares the database, the bucket, the auth handler that maps a token to a driver or support session, the topic and the upload endpoint:
// pod/pod.go
package pod
import (
"context"
"crypto/rand"
"crypto/sha256"
"encoding/hex"
"errors"
"fmt"
"io"
"math"
"net/http"
"slices"
"strings"
"time"
"encore.dev"
"encore.dev/beta/auth"
"encore.dev/beta/errs"
"encore.dev/pubsub"
"encore.dev/rlog"
"encore.dev/storage/objects"
"encore.dev/storage/sqldb"
"encore.dev/storage/sqldb/sqlerr"
)
// `encore run` starts Postgres locally; RDS or Cloud SQL in your own account when deployed.
var db = sqldb.NewDatabase("pod", sqldb.DatabaseConfig{Migrations: "./migrations"})
// Photos and signatures. Private and versioned, reached only through signed URLs.
var evidence = objects.NewBucket("pod-evidence", objects.BucketConfig{Versioned: true})
const (
maxArtifactBytes = 15 << 20
mismatchMeters = 250 // flag, do not reject: GPS is often off in dense cities
)
type Session struct {
Role string // "driver" or "support"
}
//encore:authhandler
func AuthHandler(ctx context.Context, token string) (auth.UID, *Session, error) {
sum := sha256.Sum256([]byte(token))
var uid, role string
err := db.QueryRow(ctx, `
SELECT user_id, role FROM api_tokens
WHERE token_hash = $1 AND expires_at > now()`, hex.EncodeToString(sum[:])).Scan(&uid, &role)
if errors.Is(err, sqldb.ErrNoRows) {
return "", nil, &errs.Error{Code: errs.Unauthenticated, Message: "invalid token"}
} else if err != nil {
return "", nil, err
}
return auth.UID(uid), &Session{Role: role}, nil
}
// DeliveryStatus feeds tracking pages, customer notifications and partners.
type DeliveryStatus struct {
EventID string `json:"event_id"`
StopID string `json:"stop_id"`
ShipmentID string `json:"shipment_id"`
Outcome string `json:"outcome"`
At time.Time `json:"at"`
}
var StatusEvents = pubsub.NewTopic[*DeliveryStatus]("delivery-status", pubsub.TopicConfig{
DeliveryGuarantee: pubsub.AtLeastOnce,
})
type UploadParams struct {
Kind string `json:"kind"` // "photo" or "signature"
}
type UploadResponse struct {
ArtifactID string `json:"artifact_id"`
UploadURL string `json:"upload_url"`
}
// RequestUpload gives the driver app a short-lived URL to PUT one image to.
//
//encore:api auth method=POST path=/stops/:stopID/pod/uploads
func RequestUpload(ctx context.Context, stopID string, p *UploadParams) (*UploadResponse, error) {
if p.Kind != "photo" && p.Kind != "signature" {
return nil, &errs.Error{Code: errs.InvalidArgument, Message: "kind must be photo or signature"}
}
if err := requireAssignedStop(ctx, stopID); err != nil {
return nil, err
}
id := newID()
key := fmt.Sprintf("pod/%s/%s", stopID, id)
if _, err := db.Exec(ctx, `
INSERT INTO pod_artifacts (id, stop_id, kind, object_key) VALUES ($1, $2, $3, $4)`,
id, stopID, p.Kind, key); err != nil {
return nil, err
}
// 15 minutes leaves room for a weak signal on the doorstep.
u, err := evidence.SignedUploadURL(ctx, key, objects.WithTTL(15*time.Minute))
if err != nil {
return nil, err
}
return &UploadResponse{ArtifactID: id, UploadURL: u.URL}, nil
}
Completion checks the objects, writes the event in a transaction and publishes after commit. The subscriber sends one notification per event:
type CompleteParams struct {
EventID string `json:"event_id"` // generated by the app, reused on retry
Outcome string `json:"outcome"` // "delivered" or "attempted"
Reason string `json:"reason,omitempty"`
RecipientName string `json:"recipient_name,omitempty"`
CapturedAt time.Time `json:"captured_at"`
Lat float64 `json:"lat"`
Lng float64 `json:"lng"`
ArtifactIDs []string `json:"artifact_ids"`
}
type CompleteResponse struct {
EventID string `json:"event_id"`
DistanceM int `json:"distance_m"`
Flagged bool `json:"flagged"`
}
// Complete records a delivery or a failed attempt with its evidence.
//
//encore:api auth method=POST path=/stops/:stopID/pod
func Complete(ctx context.Context, stopID string, p *CompleteParams) (*CompleteResponse, error) {
if p.EventID == "" || (p.Outcome != "delivered" && p.Outcome != "attempted") {
return nil, &errs.Error{Code: errs.InvalidArgument, Message: "event_id and a valid outcome are required"}
}
if p.Outcome == "attempted" && p.Reason == "" {
return nil, &errs.Error{Code: errs.InvalidArgument, Message: "attempts need a reason"}
}
driver, _ := auth.UserID()
// A retry of a submission that already landed returns the stored result.
var prev CompleteResponse
err := db.QueryRow(ctx, `
SELECT id, distance_m FROM delivery_events WHERE id = $1 AND stop_id = $2 AND driver_id = $3`,
p.EventID, stopID, string(driver)).Scan(&prev.EventID, &prev.DistanceM)
if err == nil {
prev.Flagged = prev.DistanceM > mismatchMeters
return &prev, nil
} else if !errors.Is(err, sqldb.ErrNoRows) {
return nil, err
}
if err := requireAssignedStop(ctx, stopID); err != nil {
return nil, err
}
var shipmentID string
var stopLat, stopLng float64
var sigRequired bool
if err := db.QueryRow(ctx, `
SELECT shipment_id, lat, lng, signature_required FROM stops WHERE id = $1`, stopID,
).Scan(&shipmentID, &stopLat, &stopLng, &sigRequired); err != nil {
return nil, err
}
// Every artifact must belong to this stop and be present in the bucket.
// The first successful check records the object version; later downloads use it.
kinds := map[string]bool{}
for _, id := range p.ArtifactIDs {
var key, kind string
var versionID *string
err := db.QueryRow(ctx, `
SELECT object_key, kind, version_id FROM pod_artifacts WHERE id = $1 AND stop_id = $2`, id, stopID).Scan(&key, &kind, &versionID)
if errors.Is(err, sqldb.ErrNoRows) {
return nil, &errs.Error{Code: errs.InvalidArgument, Message: "unknown artifact " + id}
} else if err != nil {
return nil, err
}
attrs, err := evidence.Attrs(ctx, key)
if errors.Is(err, objects.ErrObjectNotFound) {
return nil, &errs.Error{Code: errs.FailedPrecondition, Message: "upload not finished for " + id}
} else if err != nil {
return nil, err
}
if attrs.Size > maxArtifactBytes {
return nil, &errs.Error{Code: errs.InvalidArgument, Message: "artifact too large: " + id}
}
if versionID == nil {
if _, err := db.Exec(ctx, `
UPDATE pod_artifacts SET size_bytes = $1, version_id = $2
WHERE id = $3 AND stop_id = $4 AND version_id IS NULL`,
attrs.Size, attrs.Version, id, stopID); err != nil {
return nil, err
}
}
kinds[kind] = true
}
if p.Outcome == "delivered" && !kinds["photo"] {
return nil, &errs.Error{Code: errs.FailedPrecondition, Message: "a delivery needs at least one photo"}
}
if p.Outcome == "delivered" && sigRequired && !kinds["signature"] {
return nil, &errs.Error{Code: errs.FailedPrecondition, Message: "this stop requires a signature"}
}
dist := int(math.Round(distanceMeters(p.Lat, p.Lng, stopLat, stopLng)))
tx, err := db.Begin(ctx)
if err != nil {
return nil, err
}
defer tx.Rollback()
res, err := tx.Exec(ctx, `
INSERT INTO delivery_events (id, stop_id, driver_id, outcome, reason, recipient_name,
captured_at, lat, lng, distance_m, artifact_ids)
VALUES ($1, $2, $3, $4, NULLIF($5, ''), NULLIF($6, ''), $7, $8, $9, $10, $11)
ON CONFLICT (id) DO NOTHING`,
p.EventID, stopID, string(driver), p.Outcome, p.Reason, p.RecipientName,
p.CapturedAt, p.Lat, p.Lng, dist, p.ArtifactIDs)
if sqldb.ErrCode(err) == sqlerr.UniqueViolation {
return nil, &errs.Error{Code: errs.AlreadyExists, Message: "stop already has a delivery"}
} else if err != nil {
return nil, err
}
if res.RowsAffected() == 1 {
if _, err := tx.Exec(ctx, `
UPDATE pod_artifacts SET status = 'attached' WHERE id = ANY($1) AND stop_id = $2`,
p.ArtifactIDs, stopID); err != nil {
return nil, err
}
if _, err := tx.Exec(ctx, `
UPDATE stops SET status = $2 WHERE id = $1 AND status <> 'delivered'`, stopID, p.Outcome); err != nil {
return nil, err
}
}
if err := tx.Commit(); err != nil {
return nil, err
}
if _, err := StatusEvents.Publish(ctx, &DeliveryStatus{
EventID: p.EventID, StopID: stopID, ShipmentID: shipmentID, Outcome: p.Outcome, At: p.CapturedAt,
}); err != nil {
return nil, err
}
return &CompleteResponse{EventID: p.EventID, DistanceM: dist, Flagged: dist > mismatchMeters}, nil
}
var _ = pubsub.NewSubscription(StatusEvents, "notify-customer", pubsub.SubscriptionConfig[*DeliveryStatus]{
Handler: func(ctx context.Context, e *DeliveryStatus) error {
res, err := db.Exec(ctx, `INSERT INTO notifications_sent (event_id) VALUES ($1) ON CONFLICT DO NOTHING`, e.EventID)
if err != nil || res.RowsAffected() == 0 {
return err // nil on a redelivery
}
// Send the "delivered" or "we tried" message with your SMS or email provider here.
rlog.Info("customer notified", "shipment", e.ShipmentID, "outcome", e.Outcome)
return nil
},
})
The lookup and the helpers:
type Evidence struct {
Kind string `json:"kind"`
URL string `json:"url"`
}
type EventView struct {
ID string `json:"id"`
Outcome string `json:"outcome"`
Reason string `json:"reason,omitempty"`
RecipientName string `json:"recipient_name,omitempty"`
DriverID string `json:"driver_id"`
CapturedAt time.Time `json:"captured_at"`
ReceivedAt time.Time `json:"received_at"`
DistanceM int `json:"distance_m"`
Flagged bool `json:"flagged"`
Evidence []Evidence `json:"evidence"`
}
type LookupResponse struct {
StopID string `json:"stop_id"`
Status string `json:"status"`
Events []EventView `json:"events"`
}
// Lookup is what support opens when a customer says the parcel never arrived.
//
//encore:api auth method=GET path=/support/stops/:stopID/pod
func Lookup(ctx context.Context, stopID string) (*LookupResponse, error) {
if s, _ := auth.Data().(*Session); s == nil || s.Role != "support" {
return nil, &errs.Error{Code: errs.PermissionDenied, Message: "support only"}
}
out := &LookupResponse{StopID: stopID}
if err := db.QueryRow(ctx, `SELECT status FROM stops WHERE id = $1`, stopID).Scan(&out.Status); errors.Is(err, sqldb.ErrNoRows) {
return nil, &errs.Error{Code: errs.NotFound, Message: "no such stop"}
} else if err != nil {
return nil, err
}
rows, err := db.Query(ctx, `
SELECT e.id, e.outcome, COALESCE(e.reason, ''), COALESCE(e.recipient_name, ''), e.driver_id,
e.captured_at, e.received_at, COALESCE(e.distance_m, 0),
COALESCE(array_agg(a.id || chr(9) || a.kind) FILTER (WHERE a.id IS NOT NULL), '{}')
FROM delivery_events e
LEFT JOIN pod_artifacts a ON a.id = ANY(e.artifact_ids)
WHERE e.stop_id = $1
GROUP BY e.id
ORDER BY e.captured_at`, stopID)
if err != nil {
return nil, err
}
defer rows.Close()
for rows.Next() {
var v EventView
var artifacts []string
if err := rows.Scan(&v.ID, &v.Outcome, &v.Reason, &v.RecipientName, &v.DriverID,
&v.CapturedAt, &v.ReceivedAt, &v.DistanceM, &artifacts); err != nil {
return nil, err
}
v.Flagged = v.DistanceM > mismatchMeters
slices.Sort(artifacts)
for _, a := range artifacts {
id, kind, _ := strings.Cut(a, "\t")
v.Evidence = append(v.Evidence, Evidence{Kind: kind, URL: "/support/pod/artifacts/" + id})
}
out.Events = append(out.Events, v)
}
return out, rows.Err()
}
// GetArtifact streams the pinned object version for support. Encore signed
// download URLs do not take a version, so this is what keeps a later PUT
// from changing the evidence that was attached.
//
//encore:api auth raw method=GET path=/support/pod/artifacts/:artifactID
func GetArtifact(w http.ResponseWriter, req *http.Request) {
if s, _ := auth.Data().(*Session); s == nil || s.Role != "support" {
errs.HTTPError(w, &errs.Error{Code: errs.PermissionDenied, Message: "support only"})
return
}
artifactID := encore.CurrentRequest().PathParams.Get("artifactID")
var key string
var versionID *string
err := db.QueryRow(req.Context(), `
SELECT object_key, version_id FROM pod_artifacts WHERE id = $1`, artifactID,
).Scan(&key, &versionID)
if errors.Is(err, sqldb.ErrNoRows) {
errs.HTTPError(w, &errs.Error{Code: errs.NotFound, Message: "no such artifact"})
return
} else if err != nil {
errs.HTTPError(w, err)
return
}
var opts []objects.DownloadOption
if versionID != nil && *versionID != "" {
opts = append(opts, objects.WithVersion(*versionID))
}
reader := evidence.Download(req.Context(), key, opts...)
if err := reader.Err(); err != nil {
errs.HTTPError(w, err)
return
}
defer reader.Close()
w.Header().Set("Content-Type", "application/octet-stream")
_, _ = io.Copy(w, reader)
}
// requireAssignedStop lets a driver act only on stops assigned to them.
func requireAssignedStop(ctx context.Context, stopID string) error {
uid, _ := auth.UserID()
var ok bool
err := db.QueryRow(ctx, `
SELECT true FROM stops WHERE id = $1 AND driver_id = $2 AND status <> 'delivered'`,
stopID, string(uid)).Scan(&ok)
if errors.Is(err, sqldb.ErrNoRows) {
return &errs.Error{Code: errs.PermissionDenied, Message: "stop is not assigned to you or is already delivered"}
}
return err
}
// distanceMeters is the haversine distance between two coordinates.
func distanceMeters(lat1, lng1, lat2, lng2 float64) float64 {
const r = 6371000.0
rad := math.Pi / 180
dLat, dLng := (lat2-lat1)*rad, (lng2-lng1)*rad
a := math.Sin(dLat/2)*math.Sin(dLat/2) +
math.Cos(lat1*rad)*math.Cos(lat2*rad)*math.Sin(dLng/2)*math.Sin(dLng/2)
return 2 * r * math.Asin(math.Sqrt(a))
}
func newID() string {
b := make([]byte, 12)
_, _ = rand.Read(b) // crypto/rand.Read does not fail on supported platforms
return hex.EncodeToString(b)
}
The code passes go vet and Encore's compiler, and the SQL was run against Postgres 17: a token for another driver did not match the stop, a retried event ID inserted nothing, a second delivered event for the stop was refused by the partial index while an earlier attempt stayed, a delivered stop could not be set back to attempted, and the lookup returned both events in order with their artifacts. The distance function gives about 40 m for two points a few doors apart in Vienna.
Pub/Sub retries a subscriber that returns an error, so a failed insert in the notification handler is retried rather than lost. Locally, encore run stores bucket objects on the local filesystem, so the upload and lookup flow needs no cloud account during development.
Connect your AWS account as described in Connect your cloud account and run git push encore. Encore builds the image, creates the database, the bucket, the topic and its queue, and wires the subscription to the service.
pending artifacts that were never attached after a day.distance_m per region after a few weeks and tune it, and send flagged deliveries to a review queue instead of the driver.Proof of delivery is the record a carrier keeps to show a parcel reached the customer: a delivery event with the time, the driver, the device location and the recipient name, plus at least one photo and, for some shipments, a signature. Support uses it to answer a customer who says the parcel never arrived.
The backend registers the artifact and returns a short-lived signed upload URL for a private bucket, and the app PUTs the image straight to object storage. The delivery submission then lists the artifact IDs, and the backend checks that each object exists, belongs to the stop and is under a size limit before it records the delivery.
Let the app generate an event ID when the driver taps Complete and reuse it on every retry. Insert the event with ON CONFLICT DO NOTHING on that ID and return the stored result for a repeat, and add a partial unique index so a stop can have only one delivered event.
Declare the database, a private versioned bucket and a delivery-status topic in Go next to the handlers. The upload endpoint returns a signed URL, the completion endpoint checks the objects and writes the event in a transaction, a subscription notifies the customer, and deploys provision RDS, S3, SNS and SQS in your own AWS account.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.