Why test first
The fastest way to understand Grasshopper webhooks is to watch real deliveries arrive before you build anything. webhook.site gives you a free, instant HTTPS endpoint that captures every request sent to it and displays the full headers and JSON body in real time. No signup, no code, no server.
Use it to:
- Confirm your webhook subscription is registered and firing
- See the exact
msg_infoandorderpayload for each topic you subscribe to - Verify event timing and ordering as orders move through the lifecycle
- Capture real sample payloads to build your parser and test fixtures against
At a glance
Five steps, about ten minutes, zero code.
Get a test URL
Open webhook.site and copy your unique HTTPS URL.
Register it
Give the URL and topics to your licensee for staging.
Trigger an event
Create or update an order in staging.
Inspect the delivery
Watch the payload arrive in real time.
Validate behavior
Confirm the 2xx ack and payload shape.
Step 1: Get a test URL
Go to https://webhook.site. The moment the page loads, a unique endpoint is generated for you. No account required.
Copy the value under "Your unique URL". It looks like:
https://webhook.site/a1b2c3d4-e5f6-7890-abcd-ef1234567890Keep this browser tab open. Every request sent to that URL will appear in the left panel instantly.
Grasshopper only delivers to HTTPS endpoints and expects a 2xx response within 10 seconds. webhook.site URLs are HTTPS and return 200 OK immediately by default, so your test deliveries will always be accepted on the first attempt.
Step 2: Register the URL as a webhook endpoint
Webhook endpoints are registered with your licensee, the same as any other endpoint (see Registration). For testing, ask them to point your staging webhooks at the webhook.site URL. Provide:
- URL: your webhook.site URL from Step 1
- Method:
POST - Topics: the topics you want to observe
If you're just starting, subscribe to these two topics. They fire on nearly every test action so you'll see traffic quickly:
| Topic | Fires when |
|---|---|
| order_created | An order enters Grasshopper, including via API order creation |
| order_status_changed | Any top-level order status transition |
Point staging webhooks at webhook.site, never production. Production payloads contain real customer names, addresses, phone numbers, and emails. Do not route them through a third-party inspection tool.
Step 3: Trigger a test event
The simplest trigger is creating an order through the staging API. This fires order_created within seconds:
curl --location '{{staging_url}}/api/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{access_token}}' \
--data-raw '{ "order": { ...your test order... } }'See Create order for the full request body. Other easy triggers:
- Change an order's status in the staging UI (fires
order_status_changed) - Reschedule a delivery date (fires
delivery_changed) - Add a note to an order (fires
notes_added)
Step 4: Inspect the delivery
Switch back to your webhook.site tab. Within seconds of the trigger, a new POST request appears in the left panel. Click it to see:
- Headers: content type, delivery metadata, source
- Raw body: the full JSON payload
Click "Format JSON" in the content pane to pretty-print the body. You'll see the envelope described on the Payload page:
{
"webhook_id": "wh_5fa178c2083189b168663201",
"topic": "order_created",
"msg_info": {
"timestamp": "2026-07-16T14:12:09.000Z",
"shipper_id": "YOURID",
"event_origin": "system"
},
"changes": {},
"order": { ...full order snapshot... }
}What to verify
topicmatches the action you performedwebhook_idis present (you'll dedupe on this in your real receiver)order.order_idandorder.ref_order_numbermatch your test order- The
changesobject reflects the transition on update events
Use webhook.site's copy options to save the raw JSON body. Real captured payloads make far better test fixtures for your parser than hand-written samples.
Step 5: Validate response behavior
webhook.site returns 200 OK in milliseconds, which satisfies Grasshopper's delivery contract: respond 2xx within 10 seconds. That's the same contract your production receiver must meet.
While testing, also watch for duplicate deliveries. Events are asynchronous and retried, so the same webhook_id can arrive more than once. Seeing this happen live on webhook.site is the best argument for building your receiver idempotent from day one.
| Behavior | What you'll observe on webhook.site |
|---|---|
| Normal delivery | One POST per event, acknowledged instantly with 200 |
| Retry | Same webhook_id arriving again after a delay |
| Burst | Multiple events close together when one action triggers several topics |
Testing your local receiver
Once your own receiver code exists, you can forward webhook.site traffic to your local machine using their CLI, without deploying anything:
# Install: https://docs.webhook.site/cli.html (Mac / Win / Linux)
whcli forward --token=YOUR_TOKEN_ID --target=http://localhost:3000/webhooksEvery delivery that hits your webhook.site URL is replayed to your local endpoint. You keep the visual inspector and get to exercise your real handler code at the same time.
Limitations of the free tier
Free webhook.site URLs accept a limited number of requests (on the order of 100) and expire after several days unless you create an account. Once the cap is hit, new requests are rejected and won't be logged, which can look like Grasshopper "stopped sending." If deliveries stop appearing, check the request counter first, then generate a fresh URL and re-register it with your licensee.
- Never use it for production. It's an inspection tool, not infrastructure.
- Request cap and URL expiry on the free tier, as above.
- Data is visible to anyone with the URL. Treat the URL like a secret and only send staging data.
Moving to production
When the payloads look right and your parser handles them, swap the test URL for your real endpoint:
- Build your receiver: accept
POST, return2xxwithin 10 seconds, process asynchronously - Dedupe on
webhook_id(store processed IDs for at least 48 hours) - Give your licensee the production HTTPS URL and final topic list
- Keep the staging subscription pointed at your staging receiver for regression testing
Full processing best practices are on the Payload page.