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.
- 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:
actionis one ofCREATE,UPDATE, orDELETE, the operation that fires the webhook.resourceis one of ION’s webhookable entities. The schema exposes the full list: use the API Playground and inspect theResourceEnumtype.
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 thex-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:
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
createthat holds the final values. Several updates arrive as oneupdatethat holds every changed field. A chain of changes that ends in a delete arrives as onedelete.squash_typetells 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.
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:Register a receiver
Webhook receivers are registered via the GraphQL API. Create the receiver first: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:- Register against your sandbox tenant. See the Sandbox guide.
- Trigger known events. Create, update, and delete a run step in the sandbox UI, then verify your receiver logs the deliveries.
- Inspect failed deliveries. Query
webhookEventsfiltered bysubscriptionIdand theFAILEDstatus 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.