Skip to main content
A webhook endpoint is an address StockShift sends events to. Add one in the app under Settings > Webhooks, or with the webhook endpoint operations in the API.

Add an endpoint

  1. Press New endpoint.
  2. Enter the URL. It must be HTTPS and reachable on the internet. Private and local addresses are refused.
  3. Tick the events you want. The event list has the body of each one.
  4. Press Add endpoint.
  5. Copy the signing secret it shows. It is shown once. Rotate secret makes a new one.
Send test ping sends a webhook.ping event right away so you can check your endpoint.

What your endpoint receives

Each event is a POST with a JSON body:
Answer with any 2xx within 10 seconds. StockShift does not follow redirects. An event can arrive more than once and out of order. Retries keep the same id, so store it and skip events you have already handled.

Check the signature

Check the StockShift-Signature header before you trust the body. It looks like t=1760000000,v1=5257a8...:
  • t is the Unix time the event was sent.
  • v1 is the HMAC-SHA256 of <t>.<raw body> under the endpoint’s signing secret, in hex.
Compute the same HMAC over the raw body, exactly as it arrived, compare it in constant time and reject anything with a t more than five minutes old. Every SDK has a helper that does all of this:
In a Laravel app, the Laravel package adds a route that checks the signature and fires a Laravel event for each delivery.

Retries

A delivery that gets anything other than a 2xx is tried again after 1, 5, 30, 120, 360 and 720 minutes. If it still fails, or 24 hours pass, the delivery is marked failed, the endpoint is disabled and the organization’s owners get an email. Events that happen while an endpoint is disabled are not sent later. The Deliveries card on an endpoint lists its latest 50 deliveries with their status, response code, time taken and attempts. Retry sends a failed delivery once more. Deliveries are kept for 30 days. To pause an endpoint, untick Enabled and press Save endpoint.