Webhooks

Documentation Index

Fetch the complete documentation index at: https://docs.firstresonance.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

When to use webhooks vs polling

• You want low-latency reactions to changes (a few seconds end-to-end).
• You want to avoid the API call volume polling implies.
• Your downstream system can accept inbound HTTP.

• Your downstream system can’t expose an HTTPS endpoint to the internet.
• You only need data on a schedule (nightly ETL, hourly report).
• You need a strict pull-only model for compliance reasons.

​

How it works

Database change                                        Your service
     │                                                       ▲
     │ 1. ORM commit                                          │
     ▼                                                        │
PostgreSQL audit trigger ──▶ logged_actions                   │
     │                          │                             │
     │ 2. Post-commit message    │ 3. Fan-out worker queries  │
     ▼                          ▼                             │
   webhook queue ─▶ fan-out worker ─▶ send-to-receiver ──────┘
                                            (POST + HMAC)

1. A row change is committed via SQLAlchemy ORM.
2. A PostgreSQL audit trigger writes a logged_actions record with the change.
3. After commit, a message goes to the webhook queue with the transaction ID.
4. The fan-out worker reads logged_actions, builds one delivery per matching subscription, and queues each.
5. The send-to-receiver worker POSTs the JSON body to your receiver URL with the x-ion-signature header.

​

Registering a receiver

mutation CreateReceiver($input: WebhookReceiverInput!) {
  createWebhookReceiver(input: $input) {
    webhookReceiver {
      id
      name
      webhookUri
      sharedSecret      # capture this once — needed to verify signatures
      contentType
      expectedResponseCode
    }
  }
}

{
  "input": {
    "name": "Acme Production Pipeline",
    "description": "Triggers Acme ETL on run completion",
    "webhookUri": "https://hooks.example.com/ion-events",
    "contentType": "json",
    "expectedResponseCode": 200
  }
}

​

Subscribing to events

mutation Subscribe($input: WebhookSubscriptionInput!) {
  createWebhookSubscription(input: $input) {
    webhookSubscription {
      id
      resource
      action
      active
    }
  }
}

{
  "input": {
    "receiverId": 42,
    "resource": "RUN_STEP",
    "action": "UPDATE",
    "active": true
  }
}

​

Resources & actions

• action ∈ { CREATE, UPDATE, DELETE } — the database operation that fires the webhook.
• resource is one of ION’s webhookable entities. The full list is exposed by the schema (use the API Playground and inspect the ResourceEnum type).

​

Payload shape

{
  "event_id": 123456,
  "subscription_id": 42,
  "resource": "run_step",
  "action": "update",
  "transaction_id": 9876543,
  "occurred_at": "2026-04-26T19:33:42.108Z",
  "data": {
    "id": 1234,
    "etag": "abc123",
    "old": { "status": "in_progress" },
    "new": { "status": "complete", "completed_at": "2026-04-26T19:33:42.108Z" }
  }
}

data.old and data.new only contain fields that actually changed. If you need the full current state of the entity, requery it via the API using data.id. The webhook is a change notification, not a full snapshot.

​

Signature verification

params       = sorted_alphabetically([f"{k}:{v}" for k, v in data.items() if v is not None])
signed_data  = f"{webhook_uri}?{'&'.join(params)}".encode("utf-8")
signature    = base64(hmac_sha1(shared_secret.encode("utf-8"), signed_data))

import base64
import hmac
import hashlib

def verify_signature(secret: str, url: str, data: dict, header_signature: str) -> bool:
    params = [f"{k}:{v}" for k, v in sorted(data.items()) if v is not None]
    signed = f"{url}?{'&'.join(params)}".encode("utf-8")
    expected = base64.b64encode(
        hmac.new(secret.encode("utf-8"), signed, hashlib.sha1).digest()
    ).decode()
    return hmac.compare_digest(expected, header_signature)

​

Headers

​

Delivery guarantees & retries

• At-least-once. ION will redeliver if your receiver returns anything other than the configured expectedResponseCode (default 200).
• Retries follow exponential backoff. Persistent failures eventually mark the event as failed; the dispatched event is preserved in WebhookEvents for inspection.
• No ordering guarantees between independent transactions. Two updates to the same row in transaction T1 always arrive before any update in T2, but parallel transactions can interleave.
• No exactly-once. Build your receiver to be idempotent — see below.

​

Idempotency and deduplication

def handle(event):
    if seen.contains(event["event_id"]):
        return 200  # already processed; ack to stop retries
    seen.add(event["event_id"])
    process(event)
    return 200

​

Testing your receiver

1. Register against your sandbox tenant (Sandbox guide).
2. Trigger known events — create, update, delete a run step in the sandbox UI; verify your receiver logs the deliveries.
3. Inspect failed deliveries — query webhookEvents filtered by subscription_id and status = "failed" to see retry history and the request/response bodies ION recorded.

query FailedEvents($subscriptionId: Int!) {
  webhookEvents(filters: { subscriptionId: $subscriptionId, status: "failed" }) {
    id
    occurredAt
    requestData
    responseStatus
    responseData
  }
}

​

Tips

• Capture the sharedSecret immediately. It’s returned exactly once at receiver creation. If you lose it, the only fix is to rotate by deleting and recreating the receiver.
• Use a stable receiver URL. Ngrok tunnels for local testing are fine, but every URL change requires a re-registration.
• Handle the null data side correctly. data.old is null for CREATE, data.new is null for DELETE. Don’t assume both are populated.
• Don’t process synchronously past 5 seconds. ION’s send-to-receiver worker times out long-running responses; if your processing is slow, ack with 200 immediately and queue the work for an async pool downstream.
• Bring your own retry shield. ION retries on failure, but it’s still cheaper to never fail than to lean on retries — design your receiver for steady-state success.

​

Related

• Authentication — credentials needed to register receivers
• Sandbox — register and test against non-production data first
• API Playground — explore the ResourceEnum and WebhookSubscriptionActions enums
• Error Codes — the 4xx/5xx codes ION sees from your receiver