Steps
Step 1: Create an API key
Integrations → “API keys” → “Create key”. Name it after what will use it (“Online store”) and choose create. Copy the key now — this is the only time the full key is shown; if it’s lost, revoke it and create another. Send it as “Authorization: Bearer <key>”.
Keys are stored only as a hash. Each belongs to one business, and “Revoke” refuses anything using it straight away.
Step 2: Send orders
POST /api/v1/orders with your order reference as external_ref, the customer, address, date, window, items and temperature. Sending the same external_ref again updates the order; an Idempotency-Key header makes retries safe. GET the order to read its status, outcome and tracking link; POST cancel to cancel it before it’s out for delivery.
The API docs list every field and response.
Step 3: Add a webhook endpoint
“Webhook endpoints” → “Add endpoint”. Enter a URL reachable from the internet (private and local addresses are refused) and choose the “Events” you want — or none to receive every event, including ones added later. Copy the signing secret when it’s shown; it isn’t shown again.
Step 4: Verify the signature
Each request carries X-PorchRoute-Signature: sha256=<hex>, an HMAC-SHA256 of the raw request body keyed with your endpoint’s secret, plus X-PorchRoute-Event and X-PorchRoute-Delivery. Compute the HMAC over the raw bytes — not a re-serialised copy — and compare in constant time. “Rotate secret” invalidates the current secret immediately.
Step 5: Send a test and watch the log
The endpoint’s menu offers “Send test”; the row shows “Test delivered” or “Test failed” with whether your server answered 2xx. The “Delivery log” lists every attempt with its status and lets you send one again.
Step 6: Know the retry rules
A failed delivery is retried with backoff for a day. Reconciliation reports anything still owed past its grace window, so a webhook never goes missing quietly. Delivered and couldn’t-deliver events are sent after the undo window closes, so a mis-tap never reaches your system.
Good to know
- Events include stop.scheduled, stop.en_route, stop.delivered, stop.failed, stop.skipped, stop.undone and route.completed; the payload carries your external_ref, the outcome, timestamps, proof links and driver notes.
- Only owners and admins can see keys, endpoints and the delivery log.
Questions
Is the API on every plan?
Yes, Porch Light included. Plans differ by orders and texts, not features.
Why is my endpoint refused?
Endpoints must be public HTTPS addresses. Loopback, link-local and private ranges are refused, and the host is re-checked at send time.
Do API orders respect my zones?
No — deliberately. Your store already decided the order is deliverable, so API orders are never rejected or re-filtered for being outside a zone. Zones apply to orders added by hand or CSV.