Webhooks

Papaya uses webhooks to deliver real-time event data—such as order status updates—to your server. Each API key can have one or more Webhook URLs, and Papaya will POST each event to every enabled URL that has selected it.

Enabling Webhooks

When creating or editing an API key in the Papaya merchant dashboard (Settings → Open API), add one or more webhook URLs. Each URL has its own events and its own signing secret. The events you can pick depend on the key's use case:

  • Digital Ordering — order status updates (order.inKitchen, order.readyForPickup, order.complete, order.cancelled, order.reopened) for orders created via that integration, plus menus.published, channels.published and outlet.updated.

  • Reservations — order updates (order.totalsUpdated, order.statusUpdated, order.channelUpdated, order.guestCountUpdated, order.reservationInfoUpdated) for reservation-linked orders, plus channels.published.

  • Order Data — order.complete, order.cancelled and order.reopened for all orders placed through the POS, regardless of source.

  • Inventory Management — order.complete, order.cancelled, order.reopened and menus.published, for menu syncing and inventory tracking.

New URLs start with every event selected; remove the ones you don't need. URLs added before 6 November 2026 keep their previous events, so add order.reopened to them if you want it.

Payload

Every webhook is a small JSON notification, not the full resource:

{
  "id": "01K9ABCDEF0123456789XYZ",
  "event": "order.complete",
  "updatedAt": "2026-11-05T14:03:21.512Z"
}

For menus.published, id identifies that publish: each click of Publish, and each automatic send (see Published Updates), gets a new one. channels.published carries no id. Fetch the latest data with the matching GET endpoint, e.g. GET /api/v1/orders/:id or GET /api/v1/menus.

Changes to a closed bill

To change a closed bill (for example, to refund or re-take a payment), staff reopen it, make the change and close it again. Each close sends order.complete for the same id, so fetch the order and replace your copy every time. order.reopened tells you that a closed bill is being changed. A cancelled payment stays in payments[] with status: "cancelled".

General POS orders not associated with any API key will not trigger 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.

For some delivery integrations, Papaya also sends menus.published on its own: about 5 minutes after the merchant stops editing the menu (or 30 minutes after their first unsent change, if they keep editing), and only when the menu you would fetch has changed. Handle it exactly like one sent by Publish.

If you push the menu to a delivery platform, report the result with POST /api/v1/menus/publish-results, using the webhook's id as publishId.

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, or, for some delivery integrations, Papaya sends it about 5 minutes after they stop editing.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
• order.reopened
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 five reservation-linked order event:
• order.totalsUpdated
• order.statusUpdated
• order.channelUpdated
• order.guestCountUpdated
• order.reservationInfoUpdated
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*

* A failed delivery is retried several times over about 2 hours, then periodically after that. If a webhook URL keeps failing for 2 days, it's switched off; the merchant can switch it back on under Settings → Open API. A periodic GET /api/v1/orders date-range check makes sure nothing is missed while your endpoint is down.

Always return 200 OK immediately once you’ve enqueued or processed the event.

Verifying signatures

Every webhook carries a papaya-signature header, so you can check that it came from Papaya and wasn't changed on the way:

papaya-signature: t=1762351401,v1=5b3c…e9

v1 is the hex HMAC-SHA256 of <t>.<raw request body>, using the webhook URL's signing secret (the whole string, including whsec_) as the key. You'll find the secret under Settings → Open API: open the API key, then the webhook URL.

To verify a delivery, read the raw request body before parsing the JSON, compute the HMAC, and compare it with each v1 in the header:

import crypto from 'node:crypto'

export function isFromPapaya(rawBody, header, secrets) {
  const parts = header.split(',').map((part) => part.trim().split('='))
  const t = parts.find(([key]) => key === 't')?.[1]
  const signatures = parts.filter(([key]) => key === 'v1').map(([, v]) => v)
  if (!t || signatures.length === 0) return false

  return secrets.some((secret) => {
    const expected = crypto
      .createHmac('sha256', secret)
      .update(`${t}.${rawBody}`)
      .digest('hex')
    return signatures.some(
      (signature) =>
        signature.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
    )
  })
}
  • Retries keep their original t, so don't reject a delivery for being old. Use id, event and updatedAt to skip duplicates.
  • After you rotate a secret, the old one keeps working for 72 hours, and deliveries may carry a v1 for each. Accept both until then.
  • No secret on an older URL? Open it and click Create signing secret.

Republishing Order Webhooks

If your system missed webhook events or needs to reprocess orders, merchants can republish order webhooks from the Papaya dashboard:

  1. Navigate to Orders and filter by the Complete or Cancelled tab.

  2. Select the orders you want to republish, or use the ⋮ menu to bulk update all visible orders.

  3. Click Republish orders (when selecting individual orders) or Bulk update orders (from the menu).

Papaya dashboard Orders page filtered to Complete and Cancelled tabs, with the three-dot menu open in the top-right showing the
Bulk update orders
Papaya dashboard Orders page showing two completed orders selected via checkboxes, with the Actions dropdown menu open displaying the
Republish orders

This will re-send the order.complete or order.cancelled webhook events for the selected orders, allowing your system to re-fetch the latest order details via GET /api/v1/orders/:id.

For recovering from downtime or backfilling larger periods, you can either republish the order webhooks as above or use the GET /api/v1/orders date range endpoint to retrieve orders in bulk. See the Order Data and Inventory Management use cases for details.

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:

    • Verify the papaya-signature header on every request (see Verifying signatures). Webhooks don't come from fixed IP addresses, so don't allow-list by IP.

    • Optionally, also put a secret in the webhook URL's path or 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.