Being told when something changes

Omaya posts to an endpoint of yours the moment something happens. This is the right route whenever you would otherwise poll — a ticket to raise, a message to send, a workflow to start.

Setting one up

Connectors → Outbound webhooks. Give it a URL, pick the event types you care about, and keep the secret it generates.

One endpoint can take several event types, and one event type can go to several endpoints. The catalog on that page also shows which events your organisation has actually received in the last 30 days, which is usually the faster way to answer "why am I not getting anything?" — an event that has never fired for you is not a subscription problem.

Every event, what fires it, and the payload it carries.

Verify that it came from us

Each delivery is signed. Compute the same signature over the raw request body — before any parsing or re-encoding, because a re-serialised body will not match — and compare it in constant time.

The exact scheme, headers and retry schedule are on the webhook events page, which is generated from the code that sends them, so it cannot drift.

Also check the timestamp is recent. A valid old delivery that someone captured is still valid without that check.

Write the handler to be re-run

Two properties will save you a bad afternoon:

De-duplicate on the delivery id. Every retry of one logical delivery carries the same id. If your handler is not idempotent, a retry becomes a second ticket.

Answer quickly, work afterwards. Acknowledge as soon as you have the body and do the processing after. A handler that finishes its work before responding will eventually exceed the timeout, be retried, and do the work twice.

When deliveries fail

Failures are retried on a backing-off schedule for most of a day. After the last attempt the delivery is parked in the dead-letter queue, where you can see the response we got and replay it once your endpoint is healthy.

If an endpoint is failing constantly, the dead-letter queue is the place to look first — it keeps the actual response body, which is usually the whole answer.

Rules are the other half of this

A webhook tells you that something happened. A rule decides what "something" means — a threshold crossed, a room left occupied, a battery running down — and can post to your endpoint as one of its actions.

If what you want is "tell me when X", write the rule and give it a webhook action, rather than subscribing to everything and filtering at your end.