Webhooks
Webhooks
Real-time HTTP callbacks delivered to your endpoint as orders move through the network. The right way to stay in sync — never poll.
How webhooks work
- You register one or more webhook endpoints (URLs you control) with your licensee
- You subscribe each endpoint to one or more topics
- When an event occurs, Grasshopper POSTs a JSON payload to your endpoint
- Your endpoint returns a
2xxstatus within 10 seconds to acknowledge receipt
Registration
Webhook endpoints are registered with your licensee during onboarding. Provide them with:
- The HTTPS URL(s) you want to receive events at
- The list of topics you want each URL subscribed to
- Whether you want staging webhooks pointed at a separate URL
Endpoint requirements
| Requirement | Detail |
|---|---|
| Protocol | HTTPS only. HTTP endpoints are rejected. |
| Response | Return HTTP 2xx within 10 seconds. |
| Method | Webhooks are always POST with JSON body. |
| Auth | Verify the X-Grasshopper-Signature header. See Verifying webhooks. |
Retry behavior
If your endpoint returns a non-2xx status or fails to respond within 10 seconds, the delivery is queued for retry on an exponential backoff:
- Retry 1: after 30 seconds
- Retry 2: after 2 minutes
- Retry 3: after 10 minutes
- Retry 4+: exponential up to 24 hours total
After 24 hours of failures, the delivery is abandoned and logged.
Build for idempotency
Retries mean duplicate deliveries. Always check webhook_id against your processed-events table before acting.