Webhook
A webhook is an HTTP request a system makes to a URL you supply, when something happens. Instead of your systems repeatedly asking a vendor “has anything changed”, the vendor tells you. It is the difference between checking the letterbox every ten minutes and having post delivered.
| Property | Webhook | Polling | Message queue |
|---|---|---|---|
| Latency to your system | Seconds | Half the poll interval on average | Seconds |
| Cost when nothing happens | Zero | Every poll, forever | Near zero |
| Who must be reachable | You, from the public internet | The vendor only | Neither — both reach the broker |
| Behaviour when your endpoint is down | Retries, then disables — you may lose events | Nothing lost; you catch up when you return | Nothing lost; messages wait in the queue |
| Ordering guarantee | None. Retries reorder events | You control the order you read in | Usually per-partition ordering |
| Duplicate delivery | Expected. Retries produce them | Not applicable | Expected under at-least-once |
| Setup burden on the district | A public HTTPS endpoint plus signature verification | A scheduled job and credentials | Broker infrastructure both sides agree on |
| Realistic K-12 fit | Good, if someone owns the endpoint | Best default for most districts | Rare outside large districts |
The security controls a webhook sender must implement
- Signature over the raw body and a timestamp. Without it, anyone who learns your endpoint URL can post fabricated events. Kastr sends
X-Kastr-Signature: sha256=<hmac>computed over"${timestamp}.${rawBody}". - Timestamp tolerance on the receiver. A valid signature is valid forever unless the timestamp is checked; five minutes is the conventional window. This is what prevents replay of a captured request.
- SSRF validation on the destination. The URL is user-supplied, so the sender must resolve it and refuse loopback, private and link-local addresses. See SSRF for why string checking is inadequate.
- TLS required. Payloads carry student-adjacent data; plain HTTP destinations should be refused rather than warned about.
- Secret rotation without downtime. The receiver accepts old and new during a transition window longer than the retry schedule.
- Automatic endpoint disable. An endpoint failing indefinitely is either misconfigured or hostile; either way it should stop being called. Kastr disables after ten consecutive failures.
Retries, and the delivery window they produce
Kastr retries on a backoff of 1, 2, 5, 15, 60 and 360 minutes. That sequence is worth reading as a total rather than as steps: the final attempt occurs about 7 hours and 43 minutes after the first, which is the window in which a district's endpoint can be down without events being lost.
That number should drive two operational decisions. First, a maintenance window on your receiving system that is shorter than the window loses nothing. Second, when rotating a signing secret, the old secret must remain acceptable for longer than the window, or a retry of a delivery first attempted before the rotation will be rejected.
Retries are also the reason receivers must be idempotent. A delivery that your system processed successfully but failed to acknowledge within the timeout will arrive again, so the handler must recognise a repeated event identifier and do nothing. See idempotency keys.
Why a district should care
Webhooks are how a communications platform tells the rest of your estate what happened without anyone writing a polling job: a delivery failed, a guardian opted out, a roster sync aborted, a message was sent. The realistic uses in a district are unglamorous and valuable — pushing hard delivery failures into a data-quality worklist so somebody actually fixes bad numbers, mirroring opt-outs into the SIS so the record of consent is not split across two systems, and alerting when a nightly roster sync aborts rather than discovering it three days later.
The prerequisite is a public HTTPS endpoint somebody owns, which is a real constraint for a district without an integration team. If that is not available, polling the API on a schedule is the better pattern and there is no shame in it: it is more robust, easier to debug, and loses nothing when your systems are down.
The common misconception
"A webhook is just an API." The direction is what matters. With an API you are the client: you decide when to call, you see the response, and you retry on your own terms. With a webhook you are the server: the vendor decides when to call, your endpoint must be publicly reachable and always available, and you must verify that the caller is who it claims to be. The security responsibilities invert, and the most common integration failure in K-12 is a district standing up a receiving endpoint that verifies nothing.
Kastr's webhook surface sits alongside 28 org-scoped REST endpoints and an MIT-licensed CLI and MCP server — 16 commands, 19 MCP tools — in a public repository. That last point is the one worth weighing in procurement: tooling under a permissive licence keeps working whether or not the commercial relationship does.
Questions people actually ask
What is the difference between a webhook and an API?
Direction, and with it responsibility. Calling an API makes you the client — you choose the timing and handle failure. Receiving a webhook makes you the server — you must be publicly reachable, always available, and you must verify the caller's signature, because otherwise anyone who learns the URL can post whatever they like into your systems.
How do you verify that a webhook really came from the sender?
Recompute the HMAC over the exact raw bytes received plus the transmitted timestamp, using the shared secret, and compare with a constant-time function. Check the timestamp falls within a tolerance window, typically five minutes, before accepting. TLS alone proves nothing about who produced the payload.
What should happen when a webhook endpoint keeps failing?
Retry on an exponential backoff over several hours, then disable the endpoint and notify the account. Kastr uses 1, 2, 5, 15, 60 and 360 minutes — a window of roughly 7 hours 43 minutes — and disables after ten consecutive failures. Retrying forever wastes capacity and can amount to a denial-of-service against a customer's own infrastructure.
Why is signing over the raw body important?
Because parsing and re-serialising JSON changes the bytes — key order, whitespace, number formatting — and the hash changes with them. Signing the exact received bytes is the only construction where both sides reliably compute the same value, which in practice means capturing the body before any JSON middleware consumes it.
One price. Every feature. Locked for three years.
$3.50 per student per year under 5,000 students. No tiers, no add-on modules, no per-message fees. Published on the site because you should not have to book a call to learn a price.