External Push Provider (Push Hook)

← API Index

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

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

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

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):

Statistics are kept for about four months.

Don't forget

Ideas

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