Self-test your skill endpoint before going live

Before your endpoint answers real agents, test it with your own data. Sill tests your endpoint when you save it, but Sill has no access to your orders, so it cannot check the most important thing: that a real order number with the wrong customer email returns nothing.

Everything on this page runs on your machine. Sill never sees your test orders, emails or responses.

What Sill checks when you save the endpoint

When you save the endpoint, and whenever you click Re-run activation battery, Sill runs these checks. The skill goes live only if all of them pass:

1. Reachable. A GET to your endpoint returns any status from 200 to 499. A network error, timeout or 5xx fails.
2. Rejects unsigned requests. A POST with no X-Sill-Signature header must get a non-2xx response.
3. Rejects wrong signatures. A POST with an invalid signature must get a non-2xx response.
4. Answers correctly. A correctly signed POST with made-up, schema-valid arguments must get 404, or a 2xx response that matches the skill’s response schema.

Test requests carry the X-Sill-Probe: 1 header and a schema-valid body with made-up values; see Activation checks. Sill runs the same checks when it re-checks an endpoint that was marked UNREACHABLE.

What only you can check

Run each of these with real orders before going live, and again after every change to your handler.

1. Real order, wrong email: nothing returned. Pair a real order number with an email that does not own it. Your endpoint must return 404 with an empty body.
2. Real order, right email: only the listed fields. The response contains only the fields in the response schema: no customer name, address, phone, payment method or notes.
3. Unknown order and wrong email look the same. Both return 404 with an empty body, so a caller cannot tell which order numbers exist.
4. Emails are compared in constant time, as in the compare function.
5. A customer with several orders gets only the one asked for. A request for order A returns order A, even if the same email also owns orders B and C.
6. Old signatures are rejected. A correctly signed request whose t is more than 5 minutes from your server’s clock is refused.

Send one signed request by hand

Fill in your secret, endpoint, and a real order number and email, then run:

SECRET='paste-the-secret-from-the-dashboard'
ENDPOINT='https://shop.example.com/sill/skills'
BODY='{"skill_id":"order_status","site_id":"01K00000000000000000000000","arguments":{"order_id":"#1001","customer_email":"buyer@example.com"},"observed_at":"2026-07-07T00:00:00.000Z","nonce":"selftest0000000000000000000000"}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')
curl -sSi -X POST "$ENDPOINT" \
  -H 'content-type: application/json' \
  -H "x-sill-signature: t=$T,v1=$SIG" \
  --data "$BODY"

You should get 200 and the order. Then change customer_email in BODY to an email that does not own the order and run all of it again (the signature must be recomputed for the new body). You should get 404 with an empty body.

Run the automated check

sill-endpoint-check.mjs is a single file that needs only Node.js 18 or later, with no packages to install. Using the order_status skill, it runs Sill’s reachability and signature checks, sends a correctly signed request for your real order (which must return 200 with a response that matches the schema), and runs the wrong-email check.

curl -sSLo sill-endpoint-check.mjs https://docs.sill.so/skills/v1/sill-endpoint-check.mjs

SILL_ENDPOINT_URL="https://shop.example.com/sill/skills" \
SILL_SKILL_SECRET="paste-the-secret-from-the-dashboard" \
SILL_TEST_ORDER_ID="#1001" \
SILL_TEST_ORDER_EMAIL="buyer@example.com" \
SILL_TEST_WRONG_EMAIL="notmine@example.com" \
  node sill-endpoint-check.mjs

Variable	Notes
SILL_ENDPOINT_URL	Your order_status endpoint. Must be https://; http://localhost and http://127.0.0.1 are allowed for local testing.
SILL_SKILL_SECRET	The secret Sill showed you when you saved the endpoint. If you no longer have it, click Rotate secret in Settings → Skills.
SILL_TEST_ORDER_ID	A real order number. Test or sandbox orders are fine.
SILL_TEST_ORDER_EMAIL	The email that owns that order.
SILL_TEST_WRONG_EMAIL	An email that no customer in your database uses. If it belongs to the same customer, a leaking endpoint can still pass.
SILL_SITE_ID	Optional. Your site ID, if your handler checks it.
SILL_REQUEST_TIMEOUT_MS	Optional. Per-request timeout, 1000 to 60000. Default 10000.

Each check prints [PASS], [WARN] or [FAIL] with a short reason. The script never prints your secret or your endpoint’s response body.

Sill endpoint check — https://shop.example.com/sill/skills

  [PASS] reachability                                   endpoint responded (HTTP 405).
  [PASS] signature: unsigned request                    endpoint rejected the unsigned request (HTTP 401).
  [PASS] signature: wrong-secret request                endpoint rejected the bad-signature request (HTTP 401).
  [PASS] happy-path: real order + real email            response validated against the canonical order_status shape (HTTP 200).
  [PASS] customer scoping: real order + WRONG email     endpoint returned HTTP 404 for a wrong-email request against a real order id — correct.

Result: all 5 checks passed. Endpoint ready.

• [FAIL] must be fixed before going live. The most serious is a wrong-email request that returns the order’s line items.
• [WARN] means no order data leaked, but the wrong-email response still differs from “not found”. Return 404 with an empty body instead. A 2xx response that does not match the schema, such as an empty body, would also count as a failed call on real traffic, and 3 in a row mark the skill UNREACHABLE.

The script exits with 0 when nothing failed, 1 when a check failed, and 2 when a variable is missing or invalid.

When every check passes

In Settings → Skills, the skill shows your endpoint with HEALTHY and ACTIVATION CHECKS PASSED.

Order status answered by the store’s own endpoint, with Sill’s activation checks passed.

If the skill later shows UNREACHABLE, your endpoint failed 3 calls in a row with an error or a response in the wrong shape. Fix it and run this self-test again. Sill re-checks unreachable endpoints on its own (after about 5 minutes, 15 minutes, 1 hour, then hourly) and lists the skill again when a check passes; click Re-run activation battery to re-check straight away.

See also

• Skill Fulfillment Contract — request, response and signature details.
• order_status — the response shape the script checks.
• track_shipment — the other customer-scoped skill; run the same checks with a track_shipment request.