Testing and receiver handling

Quick test with a disposable HTTPS endpoint

API=https://core-api.zencommerce.tech/v1/developer
URL=https://webhook.site/YOUR-UUID

# 1) Register
curl -sS -X POST "$API/register" -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","name":"Test Dev"}'
# Save api_key and api_secret from the response

# 2) Token
TOKEN=$(curl -sS -X POST "$API/auth/token" -H 'Content-Type: application/json' \
  -d '{"api_key":"wk_…","api_secret":"…"}' | jq -r .access_token)

# 3) Subscribe (store must have webhooks enabled)
curl -sS -X POST "$API/webhooks/{shop_handle}" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d "{\"name\":\"Product create\",\"event\":\"product.create\",\"url\":\"$URL\"}"

curl -sS -X POST "$API/webhooks/{shop_handle}" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d "{\"name\":\"Order create\",\"event\":\"order.create\",\"url\":\"$URL\"}"

Then create a product in the admin, or place an order on the storefront, and watch the test inbox. Prefer synthetic data with public request-capture tools — they are for testing, not production processing.

Recommended receiver sequence

• Read raw request bytes and normalize header names.
• Reject unknown subscription IDs and unexpected store associations.
• Verify the signature with the configured mode and trusted secrets.
• Parse JSON and validate the event against the subscription.
• Persist or enqueue the work in your own durable storage.
• Return 2xx within five seconds.
• Process business logic idempotently and monitor failures.

Duplicate handling

X-Webhook-Id identifies a subscription, not a unique delivery. Do not use it alone as a deduplication key. Prefer business operations that remain correct when repeated. If you digest payloads to detect exact retries, include trusted store and subscription context and bound retention.

Suggested checks