External Push Provider (Push Hook)
By default the platform sends push notifications to the standard native apps itself (see setup push notifications). With a push hook a tenant may hand that job to an external system: once a hook URL is registered, every matching push notification is not sent by the platform any more but POSTed as JSON to your URL, and your system delivers it to the devices it knows. Statistics are still collected on the platform side, so the shop's admin area and the stats API keep showing every push, including yours.
Typical reasons: you run your own app with its own Firebase project, you use a different push vendor, or you want to route push through a central notification system of the shop operator.
The Push Hook can be set up using the UI or the API.
How it differs from an event webhook
The event webhooks inform an external system about things that happened
(a push being sent is one such event, code 2034), while the platform still does its own work.
The push hook replaces the platform's delivery: it is a single, exclusive slot, it gets a
structured JSON body instead of form fields, it expects an answer, and failures are counted and
mailed. Register the hook only if your system is ready to deliver what it receives.
Using this push hook, you benefit also from all platform personalization options.
Auth
Like the webhook API, the push hook endpoints require an API-role account that has been
granted the settings permission (UPDATE_SETTINGS_ACTION_ACCESS) for the tenant — see
use_webhooks for the details. Log on with
api/logon and call the endpoints within that session. Without the role
and the permission the endpoints answer 401 not_authorized.
Register, inspect, remove
api/system/pushhook/create— create or replace the hook. Parameters:url(required, absolutehttp(s)URL),types(optional, see below),errorMail(optional, comma-separated addresses that are mailed when calls fail). Calling it again overwrites the previous configuration; changing the URL resets the error counter.api/system/pushhook/list— shows the current configuration as one PushHook entry:configured,url,types,errorMail,errorCount.api/system/pushhook/drop— removes the hook. From the next push on, the platform delivers itself again. Idempotent.
The hook can also be set by hand in the shop's admin area (developer settings, next to the event webhooks); both ways read and write the same configuration.
Secure your URL. Calls are not signed. Put a secret token into the URL you register (path or
query string, e.g. https://push.example.com/obox/hook?key=…) and reject calls without it. Use
HTTPS.
Push types (types filter)
types is a comma-separated list of the push types you want to take over. Empty means all
types. Names are case-insensitive and stored upper-case:
| Type | Sent when |
|---|---|
ORDER_REMINDER |
the order deadline for a delivery date approaches and the customer has not ordered yet |
ORDER_CHANGE |
an order was changed/confirmed by the operator |
DELIVERY_CONFIRMATION |
the driver marked the delivery as done |
DEPOSIT_REFUND_ANNOUNCE |
a deposit refund is announced |
FORGOTTEN_CART |
a customer left items in the cart |
OTP |
a one-time password for a login (time critical, see below) |
ADMIN |
a message sent by hand from the admin area ("APP Push Messages") |
SERIES |
a queued message: a message series (e.g. to an action group) or a single push queued by the PCG backend - one call per recipient, throttled, with serieRef set |
A push whose type is not in the list keeps going the platform's own way. This lets you start
with e.g. ADMIN,ORDER_REMINDER and widen the list later. Unknown names are rejected with
parameter_error.
What you receive
One HTTP POST per push notification, Content-Type: application/json; charset=UTF-8:
{
"sysname": "musterhof",
"batchId": "7fbbebe0-72b3-4e60-967f-dd67eb0a87f4",
"pushId": "e0f64053-b63f-4f44-aa44-8d90c60cfa4a",
"type": "ORDER_REMINDER",
"target": "2422",
"title": "Bestellerinnerung",
"message": "Bis morgen 12:00 können Sie noch bestellen …",
"imageUrl": null,
"linkUrl": "https://shop.musterhof.de/?p=cart",
"cb": "https://oekobox-online.de/v3/shop/musterhof/",
"serieRef": 0,
"sentAt": "2026-09-13T18:34:31.906"
}
| Field | Meaning |
|---|---|
sysname |
the tenant (system name) the push belongs to — one hook URL may serve several tenants |
batchId |
id of this push on the platform side, shows up as batch_id in the statistics |
pushId |
random per-push token for delivery/open analytics (see below); unique, safe to use for de-duplication |
type |
one of the push types above |
target |
the customer id (number as string) the push is addressed to, or "0" for a broadcast to all devices of the tenant |
title, message |
the notification text, already localized and personalized |
imageUrl |
optional image to show with the notification, null if none |
linkUrl |
optional deep link to open on tap, null if none |
cb |
the tenant's API base URL (with trailing slash) for the analytics callbacks |
serieRef |
reference of the message series this push belongs to (type SERIES), 0 for event pushes - lets you batch or group on your side |
sentAt |
when the platform handed the push over (ISO 8601, shop local time) |
The platform has already applied the customer's notification settings (opt-in per event) and the tenant's own rules before calling you: everything you receive is meant to be delivered.
You own the device registry. The platform does not send device tokens; it only knows the
customer. Your system must know which devices belong to which customer id of which tenant (your
app can learn the customer id after the customer logs on via the API, e.g. from
api/logon), and which devices exist at all for broadcasts (target = "0").
How to answer
- Answer
2xxquickly — the platform waits at most about 7 seconds, and the call happens while the triggering process (order deadline run, driver app, login) is running. Accept the message, queue it, and deliver asynchronously. - Optionally return a JSON body
{"recipients": 12, "accepted": 11}— the number of devices you targeted and how many your provider accepted the message for. These numbers are stored and shown in the statistics. Without a body both stay0. - Anything else — a non-
2xxstatus, a timeout, a connection error — counts as failed: the push is recorded as failed, the hook's error counter is incremented, and theerrorMailaddresses are notified on the first and then on every 10th consecutive failure. A successful call resets the counter. - There is no fallback and no retry: a failed call is not sent by the platform instead (that
could duplicate a push your system did deliver but answered late), and it is not called again.
Monitor
errorCountviapushhook/listor thefailedcolumn of stats/pushsummary1. The hook is never removed automatically; if your system is down for longer, drop the hook so the platform delivers again.
Delivery and open analytics (optional)
The platform can count how many devices received and opened each push, but only if it is told.
Forward pushId and cb unchanged as custom data fields of the notification you send to the
devices, and let the app call
POST <cb>api/client/pushdeliveredwith parameterpushIdwhen the message arrives (pushdelivered),POST <cb>api/client/pushopenedwith parameterpushIdwhen the user taps it (pushopened).
Both calls need no session and are fire-and-forget; an unknown pushId is silently ignored. The
standard apps already do exactly this (see setup push notifications),
so if you deliver to one of them, just pass the two fields through. If your push vendor reports
delivery receipts to your server instead, your server can make the same two calls.
Reading the statistics
The stats API has three push methods that also accept your API-role account (no admin session needed):
- stats/push1 — the recent sends, one PushSend
per delivery channel; yours have
channel = "external". Filter withdays,limit,channel,type. - stats/pushsummary1 — per day and channel:
sends,failed,recipients,accepted,delivered,opened(PushDayStat). - stats/pushdevices1 — how many devices are registered with the platform's own push (PushDeviceStat). Useful before a switch-over: these devices will not be reached for the types you take over unless your system knows them too.
Statistics are kept for about four months.
Don't forget
OTPis a login code. It must arrive within seconds or the login fails. Either leaveOTPout oftypes(the platform delivers it) or make sure your pipeline delivers it immediately.- Broadcasts reach everyone.
target = "0"means every device of the tenant, guests included. Check that your registry can do that before taking overADMIN. - Switch-over gap. Devices that registered with the platform's push keep working for the
types you do not take over, but for the delegated types only devices your system knows get
anything. Plan the app update / registration migration before widening
types. - Personal data. The payload contains customer ids and personalized texts. Your system becomes a processor of the shop's customer data — a data processing agreement with the shop operator is normally required, and the hook URL must be HTTPS with a secret.
- One hook per tenant. A tenant can have exactly one push hook; registering again replaces it. The event webhook slots are separate and unaffected.
- De-duplicate on
pushIdif your own queue may retry, so a customer never gets a message twice.
Ideas
- Hybrid operation. Take over only the marketing-like types (
ADMIN,SERIES,FORGOTTEN_CART) with a provider that supports rich campaigns, and leave the transactional ones to the platform. - Central notification hub. Route the hook into the shop operator's existing messaging system and let it choose per customer between push, SMS or chat.
- Own analytics. Combine
batchIdwith stats/push1 and the shop event statistics (stats/events1) to see whether reminders actually lead to orders.
Getting started
# logon (API account with settings permission)
GET <base>/api/logon4?cid=<api-account>&pass=<password>
# register the hook for two types
POST <base>/api/system/pushhook/create?oo-rf=json
url=https://push.example.com/obox/hook?key=SECRET&types=ADMIN,ORDER_REMINDER&errorMail=ops@example.com
# check it
GET <base>/api/system/pushhook/list?oo-rf=json
# send yourself a test push from the shop admin area ("APP Push Messages") and watch it arrive
# statistics
GET <base>/api/stats/push1?channel=external&oo-rf=json
# revert
POST <base>/api/system/pushhook/drop?oo-rf=json