Overview

Webhooks let your app subscribe to things happening in an account, without needing to poll the API for changes. When a subscribed event occurs, an item is created, an order is dispatched, and so on, Stok.ly sends an HTTP POST request to a URL you control, with a payload describing what happened.

How delivery works

• Payloads are signed. Each request includes a signature so your app can verify it genuinely came from Stok.ly.
• Only the response status matters. Stok.ly doesn't read or parse your response body, it only checks the HTTP status code to determine whether delivery succeeded.
• Failed deliveries are retried automatically. If your endpoint doesn't return a successful status, Stok.ly retries the delivery.
• Repeated failures disable the webhook. A webhook that keeps failing is automatically disabled rather than retried indefinitely.
• Redirects aren't followed, and requests are subject to a strict timeout, your endpoint needs to respond quickly and directly.

URI requirements

Webhook URLs go through the same validation used across the platform

• HTTPS only
• No localhost or private IP ranges
• No loopback addresses
• No internal hostnames
• Must be a valid, well-formed URI
• No credentials embedded in the URI

This is checked before every delivery, not only when the webhook is created, so a URL that later resolves somewhere disallowed (for example, through a changed DNS record) stops receiving deliveries even if it validated fine originally.

Managing your webhooks

Webhooks are created, enabled, disabled, and deleted through the API. Delivery logs are available per app, per account, so you can see what was sent and whether it succeeded.

Available topics

For the full list of events you can subscribe to, and example payloads for each, see Webhook Topics.