Skip to main content
Kira posts an event to your endpoint every time something changes. Several things in the API announce themselves only this way, so an integration that polls instead is both slower and, in places, blind. This page is what arrives, what your endpoint does with it, and what governs the endpoint itself.

​
Registering an endpoint

Endpoints live in the Developers section of the dashboard — see Access for getting one. These are the rules that govern them. Each event type goes to exactly one URL. Putting an event on a URL while another already holds it is refused with a 409 naming the holder. Pause that URL, or narrow its filter, and the event is free to claim. An event no URL subscribes to is not delivered at all. It is not queued for later either. A URL with no filter claims everything, rfi.* included, so it has to be your only active URL. To split events across several URLs, give each one an explicit filter. An endpoint is never deleted, only paused. A paused URL keeps its delivery history and still holds its events.
A signing secret is shown once, at registration, and cannot be read back. Rotating issues a new one, but not instantly: for about a minute some deliveries still carry the old signature, and there is no window where both are accepted. Plan the cutover to tolerate either for that minute.

​
The envelope

Every event has the same two keys:
event names what happened. data carries the resource it happened to. Read the event name first and branch on it — the shape of data follows from it.
Successful API responses use { message, data }. Webhooks use { event, data }. Same idea, different first key.

​
What your endpoint has to do

Answer 2xx quickly, then work. Acknowledge the delivery first and do your processing afterwards, asynchronously. A handler that writes to a database, calls another service and then answers is a handler that will time out.
Your endpoint has 30 seconds to respond. The request is cut off at that point, so acknowledge first and do the work afterwards. A cut-off counts as a transient failure and is retried.
Be idempotent. Design your handler so that processing the same event twice has no additional effect. A retry re-sends the same event_id, which is what makes retrying safe — so this is the single most valuable property a webhook handler has.

​
When a delivery fails

A delivery that fails transiently is retried automatically, four times after the first attempt, on a growing delay: 1 minute, then 5, 15 and 60. Transient means your endpoint answered 408, 429 or any 5xx, or did not answer at all — a refused connection, a TLS or DNS error, or the 30-second cut-off. A 429’s Retry-After is not read; the fixed schedule applies whatever it says. A 4xx outside that set is never retried. That is your endpoint refusing the payload, and re-sending it would fail the same way on a schedule. A redirect is not followed. A 3xx answer is a failure and is never retried, so register the final URL. Five attempts span about 80 minutes. The delays are minimums, so it can take longer. After the last attempt, the event is not sent again. A late answer counts as a failure. A 2xx after the 30-second cut-off is retried, so the same event can reach you twice. Deduplicate on event_id. Every attempt is recorded, and you can send one again. The Developers section lists each attempt from the last 90 days, with its response code and failure reason. Find one by event_id and replay it — that is how you recover an event that used up its retries. A replay sends one delivery. It keeps the original event_id and goes to the URL subscribed to that event when you replay it.

​
Order is not guaranteed

Each event is delivered on its own. A later event can arrive before an earlier one that is waiting for a retry. A replay can send an old event at any time. When order matters, read status and previous_status where the event carries them, or read the resource itself. What to do about all this is Best practices.

​
What to do next

Event catalog

Every event Kira sends, by resource.

Validate signatures

Prove a delivery came from Kira.

Test your endpoint

Make real events arrive while you build.

Best practices

What separates a handler that survives from one that does not.