n8n. Connect the steps. Keep work moving.

The package is named n8n-nodes-yallabuy and installs two nodes into your workspace:

• The YallaBuy action node: a full gateway to the Public API v1 — 19 resources and 80 operations: read and write across orders, products, inventory, customers, returns and refunds, marketing, reports, restaurant and security. Every request rides a ybapi_ key as a Bearer header, and the node shapes fields and names to the API laws for you.
• The YallaBuy Trigger node: receives signed webhook deliveries straight into your n8n workspace — it verifies the HMAC signature itself, deduplicates retries, filters to the event types you select, and emits each event as a workflow item. Without writing a single line of receiver code.

Everything documented on this page is derived from the platform's actual contract: the same pagination, scope and rate-limit laws the API enforces, and the same signature scheme the sender signs with. What you read here is what happens in production.

1. The package runs on self-hosted n8n (the community nodes contract). In the n8n UI: open "Settings" then "Community nodes" and press "Install".
2. Enter the package name: n8n-nodes-yallabuy, and accept the community-package warning.
3. Wait for installation. For a manual npm install, use the commands below inside the n8n runtime environment, then restart your instance.
4. After installation you will find "YallaBuy" and "YallaBuy Trigger" in the node panel under integrations — search for YallaBuy in the node picker.

mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
# Only if package.json does not exist yet:
npm init -y
npm install n8n-nodes-yallabuy
# Restart your n8n instance using your deployment manager.

Set up the credential once (Credentials → New → YallaBuy API). Four simple fields:

On save, n8n verifies the connection automatically with a GET to /api/v1 — a working key shows a success mark; a broken one shows the API's actual error code.

Pick a resource, then an operation — the parameter panel adapts to the chosen operation automatically. Here is the full map:

Operating rules that matter — all of them are the API's own laws, enforced by the node on your behalf:

• Pagination: any list operation exposes "Return All" — it follows the opaque cursor across every page, re-sending filters on each request because the server re-authorizes per page. Without Return All, use "Limit" from 1 to 50.
• Idempotency: keyed operations accept an Idempotency-Key. Supply a durably stored UUID for retries of the same operation; leaving it blank generates a new key per item. Read the retry guidance below before running write automations.
• Order creation: prices are re-derived from your catalog by the platform (any price sent in the payload is ignored), the channel is website only, items run 1–200 — and variant_id is required for multi-variant items.
• Dynamic pickers: fields like product, customer, branch or table populate from your actual account — a dropdown sourcing the API.
• Errors: any API rejection surfaces with its real identity — the stable code (such as SCOPE_INSUFFICIENT) plus the request_id so support can trace it. With "Continue On Fail" the node emits an error item and the workflow continues instead of stopping.

The trigger receives webhook deliveries on your n8n URL and applies the exact receiving laws documented in the webhooks guide. Registration is manual by contract — endpoint management is dashboard-only, with no registration API:

1. Place a "YallaBuy Trigger" in your workflow and activate it — copy the PRODUCTION URL shown above the canvas. The URL must be public HTTPS on port 443 or 8443 (the same security law — dev tunnels like ngrok work with the port condition).
2. In the dashboard: Settings → Webhooks (/dashboard/settings/integrations/webhooks) → create an endpoint with that URL, subscribing to the SAME event types you select in the node.
3. Copy the one-time secret (whsec_) into the credential (Webhook Signing Secret field). If you rotate the secret, put the old one in the Previous field — the trigger tries both during the overlap.
4. Press "Send test event" on the webhooks screen — within about a minute a signed ping reaches your URL and the delivery shows DELIVERED in the dashboard.

Every arriving delivery goes through this check sequence before any workflow run:

• All six headers present? Missing ones are answered 401 immediately — no workflow run.
• Signature: v1=<hex> computed as HMAC-SHA256 over ${timestamp}.${endpoint_id}.${event_id}.${delivery_id}.${body} — constant-time compare with a ±300-second freshness window. A broken signature or stale timestamp = 401.
• Deduplication remembers webhook-delivery-id for one hour per n8n instance. This is not an exactly-once guarantee across instances or after expiry; durably deduplicate your workflow’s side effects.
• Filter: an event outside the selected types (with "Listen to All Events" off) answers 200 without a run — accepted, simply not relevant to you.

When an event passes the checks, it emits one output item carrying the payload exactly as sent, plus four header echoes for workflow routing: webhook_event_type, webhook_delivery_id, webhook_event_id and webhook_endpoint_id.

These are the types you can select in the trigger (the same catalog you subscribe to in the dashboard — the two must match). Each type also has its own full-payload page in the webhooks guide at /developers/webhooks:

The unified payload shape — a fixed envelope (id, type, api_version, tenant_id) with the event details inside. A live example:

{
  "id": "mwh:coupon-redeemed:9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b:b7c8d9e0-1f2a-4b3c-9d4e-5f6a7b8c9d0e",
  "type": "coupon.redeemed",
  "api_version": "v2",
  "tenant_id": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b",
  "data": {
    "redemption_id": "b7c8d9e0-1f2a-4b3c-9d4e-5f6a7b8c9d0e",
    "coupon_id": "0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d",
    "coupon_code": "WELCOME10",
    "order_id": "3f0c8e6a-1d24-4b7f-9a3e-2c5b8d90f1aa",
    "receipt_number": "RCP-20261020-1482",
    "customer_phone": "+201001234567",
    "customer_id": "3a4b5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c6d",
    "discount_amount": 50,
    "redeemed_at": "2026-10-20T12:34:56.812450+00:00"
  }
}

Two payload notes: the three first-generation types (order.created, order.status_changed, return.created) carry their fields flat next to the envelope rather than inside data — as first-integration compatibility requires. And the payload laws are constant for all types: a 64 KB cap, items truncated at 100 with the items_truncated flag, and cost (COGS) data always stripped.

Three patterns cover most use cases — all starting from these two nodes:

• Real-time order notifications: YallaBuy Trigger (order.created) → YallaBuy/get for extra details → Telegram, Email or Slack with the order number, total and address.
• Cancellation autopilot: YallaBuy Trigger (order.cancellation_requested) → an IF node on order value or reason → YallaBuy/order decideCancellation (approve/reject) → log the decision to Google Sheets.
• Hourly compensating sync: Schedule Trigger → YallaBuy/order getMany with an updated_since filter → upsert into your database or Sheets — a safety net under the webhooks in case any delivery slips.

The Public API enforces rate limits across five classes — a 429 comes back with a Retry-After header telling you how long to wait:

• Any write request body: 64 KB maximum.
• Forbidden fields (attribution, actor_id and the like) reject the request rather than being stripped — the node never sends them in the first place.
• Persist a stable UUID and unchanged payload for retries of the same keyed operation. Never reuse a key for a new operation or changed payload; replay semantics depend on the authority. Leaving the field empty generates a fresh key per item, so rerunning a workflow may create a new operation.
• Grouped multi-store reads (such as the inventory overview) come back grouped per store — the node returns them verbatim without flattening.

One special case: a ping arrived and nothing ran — that is not a failure, that is the filter working (the test event is not among the selected types). See the trigger section's note above.