Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt

Use this file to discover all available pages before exploring further.

Zapier, n8n, and Make are no-code automation tools. They let you chain Shoppex events to hundreds of other apps — “when a Shoppex order is paid, add the buyer to my Notion CRM and ping me on Slack”. You don’t need a published Shoppex app to do this; webhooks and the REST API are enough. This tutorial covers both directions: Shoppex → automation tool (trigger), and automation tool → Shoppex (action).

​
Why no official Zapier app yet?

Shoppex doesn’t (yet) ship a Zapier-marketplace app or n8n node. That means you won’t see “Shoppex” in Zapier’s app picker. Instead, you wire it up using these tool-agnostic building blocks:
  • Webhooks for outbound (Shoppex → automation tool).
  • HTTP Request actions for inbound (automation tool → Shoppex API).
  • API keys with Authorization: Bearer for authentication.
Once you understand the pattern, you can apply it to Zapier, n8n, Make, Activepieces, or any other webhook-aware automation tool.

​
Outbound — Shoppex triggers your automation

​
Step 1 — Create a Catch Hook in your automation tool

In Zapier:
  1. Create a new Zap.
  2. Trigger app: Webhooks by Zapier.
  3. Event: Catch Hook.
  4. Zapier gives you a URL like https://hooks.zapier.com/hooks/catch/123456/abcdef/. Copy it.
n8n: similar — drop a Webhook node, set Method to POST, copy the production URL. Make: drop a Webhook module, copy the URL.

​
Step 2 — Register the webhook in Shoppex

Either through the dashboard at Settings → Developer → Webhooks, or via API: 
curl https://api.shoppex.io/dev/v1/webhooks \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
    "events": ["order:paid"]
  }'
Shoppex returns the webhook config plus a secret. Copy the secret — you’ll only see it once. (You won’t usually verify signatures in Zapier itself because Zapier doesn’t expose easy HMAC verification — but keep the secret for the day you migrate to a real backend.)

​
Step 3 — Trigger a test event

Either make a real purchase, or use the dashboard’s Send test button on the webhook configuration page. Zapier captures the payload — you’ll see the order data appear in the Zap editor. Now you can map fields into the next step.

​
Step 4 — Add the action(s)

This is where Zapier shines. Common downstream actions for order:paid:
  • Slack → “send message to #sales channel: New sale: bought for ”
  • Notion → “create database row” in your customer DB.
  • Google Sheets → “append row” to your accounting tracker.
  • Discord → “send webhook message” to a private channel.
  • Mailchimp / ConvertKit → “add subscriber” with the buyer’s email.
Zapier and n8n have hundreds of pre-built actions. The Shoppex payload gives you the buyer, the product, the gateway, the amount, and timestamps — most automations need only that.

​
What payload you get

A typical order:paid delivery body looks like: 
{
  "event": "order:paid",
  "data": {
    "uniqid": "ord_xxxxxxxxxxxx",
    "type": "PRODUCT",
    "status": "completed",
    "gateway": "STRIPE",
    "total": 49.99,
    "total_display": "$49.99",
    "currency": "USD",
    "customer_email": "[email protected]",
    "product_id": "prod_xxxxxxxxxxxx",
    "product_title": "Pro License",
    "is_developer_invoice": false
  },
  "created_at": 1716595200
}
Headers Shoppex sends with each delivery:
  • X-Shoppex-Event — the event name.
  • X-Shoppex-Delivery — unique delivery UUID (use for idempotency).
  • X-Shoppex-Timestamp — unix seconds.
  • X-Shoppex-Signature-V2 — HMAC signature (see Webhook handler in a Cloudflare Worker for verification).

​
Inbound — automation tool writes to Shoppex

The reverse direction: something happens in another app, your Zap calls Shoppex to act on it.

​
Setup

Add an HTTP Request action to your Zap (or “HTTP Request” node in n8n):
  • Method: POST (or PATCH, etc., depending on endpoint).
  • URL: https://api.shoppex.io/dev/v1/{resource}.
  • Headers:
    • Authorization: Bearer shx_your_api_key
    • Content-Type: application/json
  • Body: JSON matching the endpoint’s schema.

​
Common inbound patterns

Sync a new Stripe customer into Shoppex: When Stripe creates a new customer (Zapier trigger), call: 
POST /dev/v1/customers
{ "email": "{{stripe.customer.email}}", "name": "{{stripe.customer.name}}" }
Create an invoice from a Typeform submission: When Typeform receives a submission (Zapier trigger), call: 
POST /dev/v1/payments
{
  "title": "Custom invoice from form submission",
  "email": "{{typeform.email}}",
  "value": 99.00,
  "currency": "USD"
}
The response includes a hosted checkout URL — Zapier can then send that URL via email, Slack, etc. Add a coupon code on demand: When you tag a customer in your CRM as “VIP”, create a personal coupon: 
POST /dev/v1/coupons
{
  "code": "VIP-{{customer.id}}",
  "discount_type": "PERCENTAGE",
  "discount_value": 25,
  "max_uses": 1
}

​
OAuth — for building a real Zapier app

If you eventually publish a marketplace Zapier or n8n integration that lets other Shoppex merchants connect, you’ll switch from per-merchant API keys to OAuth 2.0:
  • Authorize URL: https://api.shoppex.io/dev/v1/oauth/authorize (auth-code flow).
  • Token URL: https://api.shoppex.io/dev/v1/oauth/token (exchange code for token).
  • Token prefix: shpat_ for access tokens (1-hour TTL), shprt_ for refresh tokens (30-day TTL).
  • Client credentials: prefixed shoc_ (client ID) and shcs_ (client secret).
For a single-merchant Zap (you running your own automations on your own shop), the personal API key from your dashboard is the right path — no OAuth needed.

​
Common pitfalls

  • Treating Zapier’s filter as a security boundary. Without HMAC verification in the automation tool, an attacker who knew your Zapier hook URL could fire fake events. Most webhook attacks are unsophisticated and Zapier hooks are obscure enough to not be a real target, but it’s worth knowing. For sensitive flows (money, irreversible actions), use a real backend that verifies signatures — see the Cloudflare Worker tutorial.
  • Zapier rate limits. Zapier paid plans have task limits per month. A high-volume order:paid event can chew through them fast — be selective about which events you forward.
  • Order is paid event being processed before fulfillment finishes. Shoppex fires order:paid once payment clears, before the fulfillment outbox (Discord roles, file delivery) has run. If your Zap depends on the buyer “having the product”, wait for order:completed or watch for the fulfillment-specific events.
  • Retry window is finite. Shoppex auto-retries failed deliveries on exponential backoff (2/4/8/16 min) for a total of 5 attempts. If Zapier is paused for longer than ~30 minutes, the delivery exhausts its retries and is marked failed — re-queue manually from the Shoppex webhooks dashboard once Zapier is back, or periodically scan recent orders via API to catch what slipped through.

Reference: Webhooks

Full event list and payload structures.