Shopify setup guide

How to put Webhook Inbox between Shopify and your existing app webhook handler. ~5 minutes. No handler code changes.

What you'll have at the end

• Shopify sends HTTPS webhooks to https://inbox.sidelabs.dev/ingest/shopify/<source_id>.
• We verify X-Shopify-Hmac-Sha256, store the raw payload, then forward it to your existing handler.
• If your handler fails, the event stays searchable in the inbox until auto retry succeeds or you replay it manually.
• Your handler code does not change.

Before you start

You need:

• Your Shopify app client secret. Shopify signs HTTPS webhooks with this secret.
• Your existing Shopify webhook handler URL.
• An admin token for Webhook Inbox — we hand this out per pilot. Email support@sidelabs.dev.

1. Create your source

A "source" pairs the Shopify app secret with the destination URL we will forward to.

curl -X POST https://inbox.sidelabs.dev/api/sources \
  -H "Authorization: Bearer $INBOX_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "id": "src_acme_shopify",
    "provider": "shopify",
    "signing_secret": "shpss_or_app_client_secret",
    "destination_url": "https://api.acme.com/shopify-webhook",
    "timeout_ms": 10000
  }'

The id is your choice (snake_case, alphanumerics + underscores). Pick something stable — the ingest URL will use it.

The signing secret is encrypted at rest on the SideLabs server and never logged.

2. Point Shopify at the inbox

In Shopify, configure the webhook subscription URL to:

https://inbox.sidelabs.dev/ingest/shopify/src_acme_shopify

Use HTTPS delivery. Webhook Inbox currently expects Shopify's standard HTTPS headers, including X-Shopify-Hmac-Sha256, X-Shopify-Topic, X-Shopify-Shop-Domain, and X-Shopify-Webhook-Id.

3. Verify the round trip

Trigger a Shopify webhook, then open the dashboard:

https://inbox.sidelabs.dev/app/

You should see one event with provider: shopify, the Shopify topic as provider_event_type, and the webhook id as provider_event_id.

4. Confirm verification works

Push a malformed payload to the ingest URL:

curl -X POST https://inbox.sidelabs.dev/ingest/shopify/src_acme_shopify \
  -H "X-Shopify-Hmac-Sha256: bad" \
  -H "X-Shopify-Webhook-Id: wh_test_bad" \
  -H "X-Shopify-Topic: orders/create" \
  -H "X-Shopify-Shop-Domain: acme.myshopify.com" \
  -H "Content-Type: application/json" \
  --data '{"id":123456789}'

Expected: 400 Bad Request. The dashboard records the request as verification_status: failed, and your destination is not called for unverified payloads.

What gets forwarded

Auto retry and replay

When the destination returns non-2xx, times out, or the network errors:

• The event is marked failed.
• A background worker retries on backoff: 1m, 5m, 15m, 1h, 4h (5 attempts).
• Each retry writes a new row to the delivery-attempts timeline. The original event is never mutated.

Manual replay is available from the dashboard or API:

curl -X POST https://inbox.sidelabs.dev/api/events/<event_id>/replay \
  -H "Authorization: Bearer $INBOX_ADMIN_TOKEN"

Common questions

Which Shopify identifier is used for deduplication?

Webhook Inbox uses X-Shopify-Webhook-Id per source. Duplicate deliveries with the same webhook id return a duplicate response and do not create a second event row.

Does this change my Shopify app code?

No. Your handler still receives the original Shopify headers and raw body. Webhook Inbox only adds X-Inbox-Event-Id and X-Inbox-Source-Id.

What if I want to roll back?

Change the Shopify webhook subscription URL back to your handler. Your app secret and handler logic do not change.

Where does data live?

On the SideLabs server hosting inbox.sidelabs.dev (Frankfurt). For self-hosted, see the self-hosted tier on the pricing page.

References

Shopify's HTTPS webhook docs describe the HMAC header and standard metadata headers we validate and store: Deliver webhooks through HTTPS and About webhooks.

Start a pilot → Stripe setup guide Vs DIY SQS / Lambda