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.

Apps add events of their own, listed on the same page under Module events. If you are connecting an ERP to the Warehouse app, those are the warehouse.* events — goods received, shipped, adjusted, counted, issued to a work order, produced — and they are what tells the ERP what happened on the floor. The Warehouse page covers the rest of that link under Connecting your ERP.

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

A delivery that gets no answer, or an answer outside 2xx, is tried six times in all: again after 1 minute, 5 minutes, 15 minutes, an hour and six hours — about seven and a half hours from the first attempt to the last. 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.