Skip to content
KiukiPlatform
Documentation

Webhooks

Events, signatures, retries, how fast deliveries come, turning off and resending.

Webhooks tell your systems as your orders and shipments move, so you don't have to keep asking. Register an https endpoint and Kiuki POSTs each event to it, signed with the endpoint's secret.

Events

EventWhen
order.placedAn order was placed. Its shipments wait for their payment (awaiting_payment is true).
order.paidThe order's payment is secured.
shipment.releasedA shipment's payment is secured and it has gone to its site.
shipment.acknowledgedThe site has the shipment and will pick it.
shipment.dispatchedThe shipment left the site; carrier and tracking are set when the site gave them.
shipment.deliveredThe shipment was delivered.
shipment.cancelledThe shipment was cancelled: cancelled_by (aggregator, site or kiuki) and reason say by whom and why.
shipment.failedKiuki gave up on the shipment: it won't be sent, as if it had been cancelled. reason says so in plain words; Kiuki's own notes about it aren't shared.
order.completedEvery shipment of the order went, was cancelled or failed, and at least one went. shipments says which.
order.cancelledEvery shipment of the order was cancelled or failed. shipments says which, and why.

An endpoint can take every event (and any added later), or only the ones you choose.

Registering an endpoint

In your dashboard, or through the API with a key that has the webhooks:write scope:

curl -s https://platform.kiuki.com/v1/webhook-endpoints -H "Authorization: Bearer $KIUKI_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/kiuki/webhooks", "events": ["shipment.dispatched", "shipment.delivered"]}'

The answer holds the endpoint's secret (whsec_...). It is shown this once only: store it with your other secrets. An endpoint belongs to the world of the key that made it: a sandbox key's endpoint gets the sandbox's events, a live key's the live ones. Each world has up to 10 endpoints.

The address must be https://, without a user name or password in it, on a public host name. Kiuki checks every address the name leads to, when you register it and again at every delivery, and refuses private, loopback, link-local, multicast and other non-public addresses: an endpoint can't make Kiuki call into a private network. Redirects aren't followed: register the address that answers.

What a delivery looks like

POST /kiuki/webhooks HTTP/1.1
Content-Type: application/json
User-Agent: Kiuki-Webhooks/1 (+https://platform.kiuki.com/docs/webhooks)
Kiuki-Event-Id: 0b7e7c8e-55d1-4c86-9a49-0f4c8f3a1d2e
Kiuki-Event-Type: shipment.dispatched
Kiuki-Delivery-Id: 7d1c...
Kiuki-Delivery-Attempt: 1
Kiuki-Signature: t=1795170662,v1=289e89c98a2c01578e8674dc756e16dfb8a6bf197c4145d0677caa09a705ba1f

{"id":"0b7e7c8e-55d1-4c86-9a49-0f4c8f3a1d2e","type":"shipment.dispatched","created_at":"2026-11-20T10:31:02Z","sandbox":true,"data":{"order":{"external_ref":"test-1001","id":"5f0c2b8a-8a51-4d47-b5f2-5f0d5b2a9c10"},"shipment":{"acknowledged_at":"2026-11-20T10:28:01Z","awaiting_payment":false,"carrier":"Sandbox Parcels","dispatched_at":"2026-11-20T10:31:02Z","id":"e2a7d3f4-1c5b-4f3e-8d2a-3b9c7e6f1a20","order_id":"5f0c2b8a-8a51-4d47-b5f2-5f0d5b2a9c10","parcels":1,"service":"STD","site_id":"6b69756b-5ab0-4000-8000-000000000101","site_name":"Sandbox Warehouse 1","status":"dispatched","temperature":"ambient","tracking_number":"SBXE2A7D3F41C5B"}}}

The body comes as above, on one line, and the signature is of exactly those bytes. To test your own check, use that body and header with the example secret whsec_example0secret0for0the0documentation0only00000, at the time in t. The same body, laid out for reading:

{
  "id": "0b7e7c8e-55d1-4c86-9a49-0f4c8f3a1d2e",
  "type": "shipment.dispatched",
  "created_at": "2026-11-20T10:31:02Z",
  "sandbox": true,
  "data": {
    "order": {
      "external_ref": "test-1001",
      "id": "5f0c2b8a-8a51-4d47-b5f2-5f0d5b2a9c10"
    },
    "shipment": {
      "acknowledged_at": "2026-11-20T10:28:01Z",
      "awaiting_payment": false,
      "carrier": "Sandbox Parcels",
      "dispatched_at": "2026-11-20T10:31:02Z",
      "id": "e2a7d3f4-1c5b-4f3e-8d2a-3b9c7e6f1a20",
      "order_id": "5f0c2b8a-8a51-4d47-b5f2-5f0d5b2a9c10",
      "parcels": 1,
      "service": "STD",
      "site_id": "6b69756b-5ab0-4000-8000-000000000101",
      "site_name": "Sandbox Warehouse 1",
      "status": "dispatched",
      "temperature": "ambient",
      "tracking_number": "SBXE2A7D3F41C5B"
    }
  }
}

Every event has id, type, created_at (when it happened), sandbox and data. Order events carry data.order; shipment events data.order (its id and your external_ref) and data.shipment. They hold only what GET /v1/orders/{id} shows you: never an address. shipment.cancelled adds cancelled_by (aggregator, that is you; site; or kiuki) and reason; shipment.failed adds reason, which says in plain words that Kiuki gave up on it (Kiuki's own notes about it aren't shared). order.placed, order.completed and order.cancelled carry the order's shipments, each with its status: a completed order can have shipments that were cancelled or failed, so tell your shopper about each one that didn't go. The reference has every field.

Checking the signature

Anyone can POST to your endpoint, so check every delivery before you trust it. Kiuki-Signature is t=<unix time>,v1=<signature>, where the signature is the hex HMAC-SHA256, keyed with the endpoint's secret (all of it, whsec_ included), of the time t, a full stop, and the raw body. Work it out yourself from the body exactly as it arrived (before any JSON parsing), compare in constant time, and refuse a t more than 5 minutes from your clock, so a captured delivery can't be played back later.

Go

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"io"
	"net/http"
	"strconv"
	"strings"
	"time"
)

// VerifyKiukiSignature checks a Kiuki webhook delivery. header is its
// Kiuki-Signature header, body the request body exactly as it arrived (not
// re-encoded JSON), secret the endpoint's secret (whsec_...). Accept the
// delivery only when it returns nil.
func VerifyKiukiSignature(secret, header string, body []byte, now time.Time) error {
	var t string
	var sigs []string
	for _, part := range strings.Split(header, ",") {
		key, value, _ := strings.Cut(strings.TrimSpace(part), "=")
		switch key {
		case "t":
			t = value
		case "v1":
			sigs = append(sigs, value)
		}
	}
	sent, err := strconv.ParseInt(t, 10, 64)
	if err != nil || len(sigs) == 0 {
		return errors.New("no t= or v1= in the Kiuki-Signature header")
	}
	if age := now.Sub(time.Unix(sent, 0)); age > 5*time.Minute || age < -5*time.Minute {
		return errors.New("the Kiuki-Signature header is over 5 minutes old, or in the future")
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(t + "."))
	mac.Write(body)
	want := hex.EncodeToString(mac.Sum(nil))
	for _, sig := range sigs {
		if hmac.Equal([]byte(sig), []byte(want)) {
			return nil
		}
	}
	return errors.New("the Kiuki-Signature header doesn't match the body")
}

// Handler is where it goes: read the body whole, check it, hand the event on
// (handle should only queue it: answer within 10 seconds), and answer 2xx.
// An event can come more than once: handle it once per event id.
func Handler(secret string, handle func(event []byte) error) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
		if err != nil {
			http.Error(w, "the body couldn't be read", http.StatusBadRequest)
			return
		}
		if err := VerifyKiukiSignature(secret, r.Header.Get("Kiuki-Signature"), body, time.Now()); err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}
		if err := handle(body); err != nil {
			http.Error(w, "not taken: send it again", http.StatusServiceUnavailable)
			return
		}
		w.WriteHeader(http.StatusNoContent)
	}
}

Python

import hashlib
import hmac
import time


def verify_kiuki_signature(secret, header, body, now=None, tolerance=300):
    """Check a Kiuki webhook delivery.

    header is its Kiuki-Signature header, body the request body as bytes,
    exactly as it arrived (not re-encoded JSON), secret the endpoint's secret
    (whsec_...). Raises ValueError unless the delivery is genuine.
    """
    t, sigs = None, []
    for part in header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t":
            t = value
        elif key == "v1":
            sigs.append(value)
    if t is None or not t.isdigit() or not sigs:
        raise ValueError("no t= or v1= in the Kiuki-Signature header")
    now = time.time() if now is None else now
    if abs(now - int(t)) > tolerance:
        raise ValueError("the Kiuki-Signature header is over 5 minutes old, or in the future")
    want = hmac.new(secret.encode(), t.encode() + b"." + body, hashlib.sha256).hexdigest()
    if not any(hmac.compare_digest(sig, want) for sig in sigs):
        raise ValueError("the Kiuki-Signature header doesn't match the body")

Node.js

const crypto = require("crypto");

// Checks a Kiuki webhook delivery. header is its Kiuki-Signature header,
// rawBody the request body as a Buffer, exactly as it arrived (not
// re-encoded JSON), secret the endpoint's secret (whsec_...). Throws unless
// the delivery is genuine.
function verifyKiukiSignature(secret, header, rawBody, nowSeconds = Math.floor(Date.now() / 1000)) {
  let t = null;
  const sigs = [];
  for (const part of header.split(",")) {
    const [key, value] = part.trim().split("=", 2);
    if (key === "t") t = value;
    else if (key === "v1") sigs.push(value);
  }
  if (!t || !/^\d+$/.test(t) || sigs.length === 0) {
    throw new Error("no t= or v1= in the Kiuki-Signature header");
  }
  if (Math.abs(nowSeconds - Number(t)) > 300) {
    throw new Error("the Kiuki-Signature header is over 5 minutes old, or in the future");
  }
  const want = crypto.createHmac("sha256", secret).update(t + ".").update(rawBody).digest("hex");
  const ok = sigs.some((sig) => sig.length === want.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want)));
  if (!ok) {
    throw new Error("the Kiuki-Signature header doesn't match the body");
  }
}

module.exports = { verifyKiukiSignature };

Answering

Answer with any 2xx status within 10 seconds; the body of your answer is ignored. Do the work after you have answered (put the event on a queue), so a slow job never makes a delivery fail.

Retries and duplicates

A delivery that gets no answer, an answer other than 2xx, or a redirect, is tried again after a pause: 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 6 hours, 8 hours after each failed attempt in turn, then every 8 hours, until a day has passed since the event. Then it is marked failed.

  • Deliveries are at least once: the same event can arrive twice (your answer was lost, say). Handle each event id once.
  • Events can arrive out of order, especially after a retry. Use the shipment's and order's status and times in the event, or GET /v1/orders/{id} for the latest.

How fast deliveries come

Kiuki paces its deliveries, so an endpoint that is slow or down holds up only itself: not your other endpoints, and not anyone else's.

  • One at a time to each endpoint. The next delivery to an endpoint waits until it has answered the one before, or the 10 seconds for an answer are up.
  • At most 3 at once to your organisation, across all its endpoints, live and sandbox together.
  • 10 seconds to answer. An attempt that gets no answer in that time has failed, and is tried again after a pause, as above.
  • An endpoint that stops answering is paused, on its own. When 3 attempts in a row to an endpoint get no answer within the 10 seconds, its deliveries wait 30 seconds; then one is tried. While that one gets no answer, the wait doubles each time, up to 5 minutes. The first answer of any kind, an error status included, ends the pause. Your other endpoints carry on meanwhile.
  • Retries for a day. However long an endpoint is paused, a delivery is tried again only until a day has passed since its event (or since you sent it again); then it is marked failed. Send it again from the delivery log once your endpoint answers.

Turning an endpoint off, and when it keeps failing

You can turn an endpoint off in the dashboard (or PATCH it with "enabled": false). If every attempt to deliver to an endpoint fails for a whole day (and at least 10 in a row), Kiuki turns it off, and the people of your organisation who use the dashboard are emailed.

While an endpoint is off nothing is sent to it, but its events aren't lost: its waiting deliveries, and every event it wants from then on, wait in its delivery log as skipped. Once it is fixed, turn it on again in the dashboard (or PATCH it with "enabled": true): up to 100 of the deliveries skipped in the last 30 days are then sent, the oldest first, each with a day of retries (only events it still wants, if you changed them meanwhile). Any more stay skipped: send the ones you need again from the log (below), or read your orders with GET /v1/orders. Deliveries older than 30 days aren't kept.

The delivery log, and sending again

Every attempt is kept for 30 days, with the status of your answer, how long it took and the start of its body: in the dashboard, and through GET /v1/webhook-endpoints/{id}/deliveries. Any delivery (failed, skipped, or delivered) can be sent again, now, with a fresh day of retries, while the endpoint is on: the dashboard's Resend button, or POST /v1/webhook-endpoints/{id}/deliveries/{delivery_id}/resend. A delivery is sent again at most 20 times.