Papaya uses webhooks to deliver real-time event data—such as order status updates—to your server. Each API key is configured with a single Webhook URL, and Papaya will POST relevant event payloads to that URL.

Enabling Webhooks

When creating an API key via the Papaya merchant dashboard, enter a valid URL in the Webhook URL field. This URL will receive event updates related to the key’s assigned use case only:

• API keys for Digital Ordering will receive updates only for orders created via that integration.

• API keys for Reservations will only receive order updates tied to those reservations.

• General POS orders not associated with the API token will not trigger these webhooks.

Published Updates

For potentially noisy updates—such as Menu or Channel changes—merchants must manually click “Publish” in the dashboard after making changes.

These types of updates are typically less frequent, but involve larger resources (e.g. full menus) that may undergo many small edits. Without publishing, each minor change could trigger excessive webhook traffic. The manual publish step ensures that only intentional, consolidated updates are sent via webhook.

In these cases, Papaya sends a lightweight webhook notifying you that the resource has changed — not the full updated data. It’s your responsibility to call the relevant GET endpoint to retrieve the latest version.

Supported webhooks

Event	Trigger	Typical Use-Case
Channels Published	A merchant clicks Publish after editing channels. event: channels.published	Refresh your local list of channels and restaurant table definitions.
Menu Published	A merchant clicks Publish after editing a menu. event: menus.published	Update menu in digital ordering apps so customers always see the latest menu.
Order Status	Order status changes triggering the event: order.inKitchen order.readyForPickup order.complete order.cancelled	Update customer UI or send notifications.
Outlet Updated	Outlet details changed in merchant dashboard. event: outlet.updated	Sync branding, opening hours, or address details in external systems.
Reservation Order Update	One of four reservation-linked order event: order.totalsUpdated order.statusUpdated order.channelUpdated order.guestCountUpdated	Pull fresh order data and apply business-specific logic (e.g. update a reservation platform’s bill, move table assignments, adjust guest count analytics).

Handling responses

HTTP Status	Meaning
200	Acknowledged – no retry will occur
≠ 200	Failure – Papaya retries with backoff*

* Papaya will retry non-2xx responses several times using exponential backoff until it succeeds or times out.

Best practices

• Idempotency: design your handler so repeated deliveries don’t cause duplicates

• Low latency: respond within < 5 seconds to avoid timeouts or retries

• Logging: record incoming payloads and responses for debugging

• Security:

  • Validate requests originate from Papaya’s IP range or via a shared secret in the URL path/query

  • Use HTTPS with a valid TLS certificate

• Monitoring: track failure rates and alert when retry thresholds are exceeded

With webhooks configured, you’ll receive realtime updates without polling—enabling faster, more efficient workflows.