Skip to main content
Webhooks let your service react to changes in ION without polling. You register a receiver, which is a URL plus a shared secret, then subscribe it to specific events. ION then posts a JSON message to your URL whenever a matching change is committed.

When to use webhooks vs polling

Use webhooks when:
  • Your system can accept inbound HTTP.
  • You want low-latency reactions to changes.
  • You want to avoid polling for changes.
Stick with polling when:
  • Your system can’t accept inbound HTTP.
  • You only need data on a schedule.
  • You need a pull-only model for compliance.

How delivery works

ION fires a webhook on the change itself, not on the API call that made it. Any committed change to a subscribed (resource, action) triggers a delivery, no matter where it came from: the GraphQL API, the ION UI, or an automated action. Once a matching change commits, ION builds one delivery per matching subscription and POSTs the JSON body to your receiver URL with the x-ion-signature header. A delivery succeeds when your receiver responds with the receiver’s expectedResponseCode, which is 200 by default. Any other response code counts as a failed delivery, and so does a response that takes longer than 45 seconds.

Event types

A subscription is a (resource, action) pair where:
  • action is one of CREATE, UPDATE, or DELETE, the operation that fires the webhook.
  • resource is one of ION’s webhookable entities. The schema exposes the full list: use the API Playground and inspect the ResourceEnum type.
Common resources customers subscribe to: ABOM_INSTALLATIONS is also subscribable. ABOM_ITEMS and ABOM_EDGES aren’t.

Payload shape

Every delivery is a JSON POST with this shape:
A delivery has no ID of its own, so there is no per-delivery key to deduplicate on. See Handle duplicate and out-of-order deliveries.
Don’t assume updated is populated. If you need the full current state of the record, requery it through the API using data.id. The webhook is a change notification, not a full snapshot.

Signature verification

Every delivery includes an HMAC signature in the x-ion-signature header. Verify it before trusting the payload. Anyone can reach your endpoint. Only you and ION hold the secret. The signature signs the receiver URL plus the data field’s keys and values (alphabetically sorted, null values excluded), not the raw body:
Implement the same construction on your side and compare:
Always use hmac.compare_digest or your language’s equivalent. A constant-time comparison prevents timing attacks.
ION writes each non-null data value into the signed string the way Python’s str writes it. A boolean is True or False, and a nested object is written as a Python dictionary with single quotes. If your receiver isn’t written in Python, reproduce that format for values that aren’t strings.

Custom headers

Custom headers are useful when your receiver sits behind an API gateway that requires its own auth, such as an internal API key. Create a header once, then add it to each receiver that needs it. ION attaches it to every delivery. ION lowercases header names, and you can’t set x-ion-signature or content-type as a custom header.

Delivery guarantees and retries

How a failed delivery is handled depends on your ION environment:
  • Retries. In some environments, ION retries a failed delivery up to two more times, about 10 seconds apart, then stops. A delivery that fails all three attempts isn’t sent again. In other environments, ION makes one attempt and doesn’t retry. In both, the failed delivery stays in the delivery log with the status FAILED.
  • Merged events. In some environments, ION merges several changes to the same record within one transaction into one event. A record that is created and then updated arrives as one create that holds the final values. Several updates arrive as one update that holds every changed field. A chain of changes that ends in a delete arrives as one delete. squash_type tells you which merge happened.
  • No ordering guarantees. ION doesn’t guarantee the order of deliveries. Events from different transactions can interleave, and a retried delivery can arrive after later ones.
  • No exactly-once. A delivery can arrive more than once, for example when your receiver processed it but answered too slowly. Build your receiver to be idempotent.
ION waits up to 45 seconds for a response. If your processing is slow, acknowledge right away with the receiver’s expected response code and queue the work to run asynchronously downstream.

Handle duplicate and out-of-order deliveries

Treat each delivery as a notice that a record changed, not as the change itself. Requery the record by its ID and apply its current state. A handler that does this gives the same result however many times, and in whatever order, the same change arrives:
Run a periodic poll as well, so that a delivery that failed all its attempts doesn’t leave your copy out of date.

Register a receiver

Webhook receivers are registered via the GraphQL API. Create the receiver first:
The sharedSecret in the response is your HMAC key for signature verification. If you omit sharedSecret on creation, ION generates one. You can also set your own, which must be at least 8 characters. You can read the secret again by querying the receiver, and change it with updateWebhookReceiver. webhookUri must use HTTPS, and a URL can belong to only one receiver. You can change it later with updateWebhookReceiver.

Subscribe to events

Add one or more subscriptions to the receiver. Each subscription is one (resource, action) tuple, and a receiver can have each tuple once:

Test the receiver

Before pointing production traffic at a new receiver:
  1. Register against your sandbox tenant. See the Sandbox guide.
  2. Trigger known events. Create, update, and delete a run step in the sandbox UI, then verify your receiver logs the deliveries.
  3. Inspect failed deliveries. Query webhookEvents filtered by subscriptionId and the FAILED status to see the response code and the request and response bodies ION recorded for the latest attempt.
numberOfRetries counts delivery attempts. An attempt that fails shows as FAILED even when ION is about to retry, and the same row updates if a retry succeeds. A delivery fails when your receiver responds with a code other than its expected response code, doesn’t respond within 45 seconds, can’t be reached, or presents a certificate that can’t be verified.

Monitor deliveries in ION

The same delivery log is browsable in the app: in ION, go to Developer Platform > Webhook Deliveries. Each row is one delivery, and a retry updates its row. The response body is usually the fastest clue when a delivery fails.