Webhooks

Webhooks push event notifications to a URL you control, so your integration reacts to changes in Fiddle the moment they happen — no polling required.

How webhooks work

1. You register a publicly reachable HTTPS endpoint.
2. You subscribe it to the events you care about (for example, when a sales order is created or stock is adjusted).
3. When an event fires, Fiddle sends an HTTP POST to your endpoint with a JSON payload describing what changed.
4. Your endpoint responds with a 2xx status to acknowledge receipt.

Register an endpoint

curl -X POST https://fiddle.io/rest/api/v2/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/fiddle",
    "events": ["sales_order.created", "stock.adjusted"]
  }'

Respond quickly and idempotently

• Return a 2xx status fast, then do heavy work asynchronously. Slow responses may be treated as failures and retried.
• Deduplicate by event ID — the same event can be delivered more than once.

If your endpoint returns an error or times out, Fiddle retries delivery with backoff. Make handlers idempotent so retries don’t create duplicate records on your side.

While developing, point a webhook at a request inspector or a tunneling tool to see live payloads before wiring up your real handler.

Next steps

Pair webhooks with the API to fetch full records — see common API recipes.